Docs: Updates README with alpha status, adds whitepaper, splits out upgrading page

[kevinrobinson]

This pull request updates some bits in the README, and aims at communicating the status of the project and the short-term intention.

First, it updates the README to show that this is an alpha release. This mirrors how interpretml describes itself.

Second, it updates the overview paragraph to echo some of the language from the whitepaper, which frames the project as aiming to serve a particular audience with particular needs.

Finally, it cuts references from the README on how to upgrade from version 0.2, since I'm assuming no one needs that anymore. It moves upgrading instructions into an upgrading page on the website that can hold those things as they are needed. This is in the webpage so that images and examples or whatever can go there, and it can be more user-facing than the changelog. I'm assuming none of these will change frequently :) and that breaking changes are likely and tolerable as long as the project as long in an alpha state. (EDIT: discussed on 6/11 and also in fairlearn/fairlearn-proposals#11)

I didn't look at the build failures, which are being discussed in #472.

[kevinrobinson]

There's the build failure from #472 but also three other failures from the "Local install of fairlearn with pip" step (pip install .) on the Windows boxes in the Azure pipeline (link to log):

ERROR: Command errored out with exit status 1:
     command: 'c:\hostedtoolcache\windows\python\3.6.8\x64\python.exe' -c 'import sys, setuptools, tokenize; sys.argv[0] = '"'"'C:\\Users\\VSSADM~1\\AppData\\Local\\Temp\\pip-req-build-hxm9tr2s\\setup.py'"'"'; __file__='"'"'C:\\Users\\VSSADM~1\\AppData\\Local\\Temp\\pip-req-build-hxm9tr2s\\setup.py'"'"';f=getattr(tokenize, '"'"'open'"'"', open)(__file__);code=f.read().replace('"'"'\r\n'"'"', '"'"'\n'"'"');f.close();exec(compile(code, __file__, '"'"'exec'"'"'))' egg_info --egg-base 'C:\Users\VSSADM~1\AppData\Local\Temp\pip-pip-egg-info-i98z0jbl'
         cwd: C:\Users\VSSADM~1\AppData\Local\Temp\pip-req-build-hxm9tr2s\
    Complete output (7 lines):
    Traceback (most recent call last):
      File "<string>", line 1, in <module>
      File "C:\Users\VSSADM~1\AppData\Local\Temp\pip-req-build-hxm9tr2s\setup.py", line 8, in <module>
        long_description = fh.read()
      File "c:\hostedtoolcache\windows\python\3.6.8\x64\lib\encodings\cp1252.py", line 23, in decode
        return codecs.charmap_decode(input,self.errors,decoding_table)[0]
    UnicodeDecodeError: 'charmap' codec can't decode byte 0x9d in position 1311: character maps to <undefined>
    ----------------------------------------
ERROR: Command errored out with exit status 1: python setup.py egg_info Check the logs for full command output.

Ah this is from setup.py#8, so that's reading in the README.md. I can't tell from the diff what the problem is, so I added an explicit "open as utf8" to setup.py to see if that will help. I'll have to let the build run and check on this later.

[kevinrobinson]

Okay, updating setup.py to read in the file as utf8 fixed the build failure on Windows boxes. I don't really understand what caused that issue, but I'm assuming it's good to make the character encoding explicit anyway, so don't think it's worth looking at any further.

[romanlutz]

I love this! Thanks a lot for helping make our docs better.

[romanlutz]

I'm not really sure how to feel about this one. Do you find this helpful to users?

I imagined what effect this would have on me if I saw this on another project. I think it would make it less likely for me to use it. We already list the alpha status in setup.py, so that makes me lean towards not adding it here as well. I know interpret does this, but we don't need to be copying from them. In terms of documentation we're probably ahead of that project (even though ours leaves A LOT to be desired right now as you know).

[kevinrobinson]

@romanlutz Yes, I think it is important to communicate the maturity of a project :)

[romanlutz]

Definitely appreciate you improving this! I was originally planning to move most of the content of the README into the website. Specifically, some of this should probably live in the new "About" section that is still pretty empty. I do realize that some people just come to the repo as opposed to the website, so perhaps we can have it in both places? What do you think?

Also @mesameki @MiroDudik @hannawallach may have thoughts on the location.

[kevinrobinson]

@romanlutz My vote is to put off structural revisions to the marketing page / website / repo documentation for now. I think what you've done is great to allow things to get started! and with that in place, focusing on the substance for a while will be more productive.

Then when there are more great examples and substance, along with a roadmap some kind of shared understanding of what audience the project is trying to reach and what it's positioning is... then it becomes more straightforward to critique whether the website serves those needs and rearrange it.

[romanlutz]

I love this! We should have done this from the start...
Clearly, we need to add a few more sections, perhaps for every new version. I don't expect that to be part of this PR, though. I can sift through the CHANGES.md afterwards and find the API changes that happened between versions.

[kevinrobinson]

I don't think it's worth spending any time on this now, especially retroactively. I'm thinking of this as a chore done in the release process.

[romanlutz]

@kevinrobinson did you see the DCO issue? It's part of the checks. It explains how to fix that issue. LMK if you have issues with that (sometimes the steps don't quite work as well as one would hope).

[kevinrobinson]

@romanlutz ah yeah thanks! you always have to do this for every commit to every pull request?

[riedgar-ms]

@romanlutz ah yeah thanks! you always have to do this for every commit to every pull request?

It should be possible to set git up to signoff automatically:
https://git-scm.com/docs/git-config#Documentation/git-config.txt-formatsignOff

I can't speak to that way, though - I have VS Code configured to do the signoff. If I commit from the command line, I always end up doing the amend/force push thing.

[romanlutz]

Looks good to me. @MiroDudik @hannawallach @mesameki @riedgar-ms any comments?

[romanlutz]

This is quite outdated at this point. I'm opening an issue for the upgrading section in case someone wants to tackle that.