[MRG] Improve contribution document

[betatim]

This adds back some sections that got lost over time and fixes typos, broken links, etc.

I followed all the individual guides to check that they work, except for the "helm chart development" one.

[betatim]

One thing I've noticed when running the tests is that test_build.py::test_build spends a lot of time doing nothing(?) between printing for example the last two lines of this test:

binderhub/tests/test_build.py::test_build[gh/binderhub-ci-repos/cached-minimal-dockerfile/596b52f10efb0c9befc0c4ae850cc5175297d71c] Waiting for build to start...
Picked Git content provider.
Cloning into '/tmp/repo2dockervu5x3rmc'...
HEAD is now at 596b52f Let README.md reference the minimal-dockerfile repo
Using DockerBuildPack builder
Step 1/1 : FROM jupyterhub/binderhub-ci-repos_minimal-dockerfile:latest
 ---> d2f558522e48
{"aux": {"ID": "sha256:d2f558522e48ff00dff80b759cdc4bf69ea58989e9dc851f1daa7d4b23ec9f29"}}[Warning] One or more build-args [NB_USER NB_UID] were not consumed
Successfully built d2f558522e48
Successfully tagged test-2df2af76eb719f8dd469e990691b74dcbb-2dbinderhub-2dci-2drepos-2dcached-2dminimal-2ddockerfile-e08ef5:596b52f10efb0c9befc0c4ae850cc5175297d71c
Built image, launching...
Launching server...
server running at http://192.168.64.2:30902/user/binderhub-ci-re-imal-dockerfile-w6hpvxwk/
http://192.168.64.2:30902/user/binderhub-ci-re-imal-dockerfile-w6hpvxwk/

The last line is printed by our unit test and indicates that it got it and it will visit the repo. The second to last line is BinderHub saying "the server is ready". So the mystery for me is why so much time (maybe 10-20seconds pass? I've not timed it but it is much more than "1-2 seconds) passes between these two.

[consideRatio]

The overview this section contain took quite some time for me to figure out by code inspection and has been important to me to comprehend - can we retain it?

[betatim]

I was thinking about having a dedicated section in the docs that contains all the nitty gritty details, how to run all the tests, other pitfalls, etc. With the goal of keeping CONTRIBUTING.md aimed at newcomers or a quick reference.

Having such a place to store commands I actually use (because CONTRIBUTING.md uses "a Ubuntu system as common denominator" would be nice.

[consideRatio]

Sure go for it!

[consideRatio]

Just wanted to explicitly request a change I find important: https://github.com/jupyterhub/binderhub/pull/1251/files#r563198058

[consideRatio]

@betatim would you like to keep working on this?

[betatim]

I won't have time to move the commands and start a new document for the nitty gritty. I think we can create a follow up issue to take care of that and merge this PR

[consideRatio]

I won't have time to move the commands and start a new document for the nitty gritty. I think we can create a follow up issue to take care of that and merge this PR

Can you be more specific with what you mean with "move the commands"?

Before a merge, I'd like to ensure the deleted section about the tests is retained in our docs. I've copy pasted it below for clarity of what I refer to.

## Running tests

This git repository contains `pytest` based tests that you can run locally.
Depending on your development setup, you may want to run different kind of
tests. You can get some hints on what tests to run and how by inspecting
`.travis.yaml`.

### Environment variables influencing tests
- `BINDER_URL`: An address of an already running BinderHub as reachable from the
  tests. If this is set, the test suite will not start temporary local BinderHub
  servers but instead interact with the remote BinderHub.
- `GITHUB_ACCESS_TOKEN`: A GitHub access token to help avoid quota limitations
  for anonymous users. It is used to enable certain tests making many calls to
  GitHub API.

### Pytest marks labelling tests
- `remote`: Tests for them the BinderHub is already running somewhere.
- `github_api`: Tests that communicate with the GitHub API a lot.
- `auth`: Tests related to BinderHub's usage of JupyterHub as an OAuth2 Identity
  Provider (IdP) for non public access.

[betatim]

Moving that section to some new document is something I'd punt to a different PR/someone else as I won't have time to work on that.

[consideRatio]

Moving that section to some new document is something I'd punt to a different PR/someone else as I won't have time to work on that.

It is my understanding that you wish that section to be either moved or deleted. It is my wish that it is retained someplace - preferably in CONTRIBUTING.md where I think it fits best.

To me, it was quite challenging to onboard myself to grasp that overview as I had to do it via code inspection. If you wish to have it moved or refactored somehow, that's okay with me, but to straight up delete it isn't.

[betatim]

Feel free to make a new PR based on this one which reflects a compromise you like.

[consideRatio]

@betatim are you asking me to accept this PR removing a section I wanted to retain, and that I submit a new PR adding this section back after this PR then is merged?

[consideRatio]

@betatim when I read #1251 (comment) I got quite sad, and I still feel sad about the interaction we had in this PR.

I remain emotional about this PR because I understand it as a the changes suggested in it stems from reverting changes I suggested in #1188 rather than iterating on the documentation. I'm willing to revert changes I've introduced, but I'm not willing to approve/merge this PR in order to create a new one myself adding them back. (EDIT: "adding them back" should have been "adding the section on running tests back")

I'm sorry that you didn't get a chance to review changes in #1188 before they were merged.

[betatim]

(At the time) I thought this was an improvement over what was in main. You disagree. This is fine. I don't feel strongly enough about this change to figure out where the compromise is, which means I propose we close this. I'm also happy for someone else to take over this PR to try and complete it.

[consideRatio]

Thank you for following up with me @betatim!

I'll for now go for a close here then. If you or someone else wants to work this, the wish I have is that the section I added about running tests is retained. I don't feel strongly about any language changes, but that information has been critical for my own development efforts in this repo.