Problem: We don't know how difficult the contribution process is

[julianpistorius]

We have a very basic, first draft of a CONTRIBUTING.rst file thanks to @ejaffe-osc & #12. We could add a lot more detailed information, but this might not be needed, and could actually overwhelm contributors. The ideal would be:

• Just enough information for people to feel confident about making contributions on their own
• With no (or minimal) help from maintainers

Idea:

1. Ask for a couple of volunteers to run through the contribution process
2. Set up a live screen sharing session with each volunteer (and make temporary recordings)
3. Ask each volunteer to follow the steps without prompting from us, while speaking their thoughts out-loud
4. Take notes on how the contributing process could be improved
5. Ask each volunteer to review the sessions of the other volunteers, as well as their own, while adding to/modifying the notes above
6. Update contributing documentation based on feedback & notes
7. Delete screen recordings

[julianpistorius]

My rough notes from the first session

• We should change the link for how to get to Codespaces. The current link takes you to information about Codespaces. We should be going to the GitHub repository.
  • Maybe we should add the contributing directions directly the top of README.md/README.rst so it's easily visible on the landing page for the repository
• We can leave out mentioning port 8080 (which is wrong anyway - it's actually 8000).
• We should be explicit about the destination/build directory - docs/build/html
• We should give instructions about how to add new pages to the navigation tree.
• We should mention adding extensions when creating files, e.g. .rst or .md
• We should remove step about pushing to our fork, since we're relying on Codespaces automatically handling forks & branches
• We should be explicit about staying in Codespaces for creating pull request
• Mention where the pull request button is and what it looks like
• We should ensure we are consistently/correctly using Raise/Create/Open/Submit (Pull Request)
  • https://docs.github.com/en/codespaces/developing-in-a-codespace/using-source-control-in-your-codespace#raising-a-pull-request
• Official GitHub Codespaces instructions mentions 'local copy', which can be confusing, since we might assume it means on our local machine
• If it says 'committing' for a long time, and apparently doing nothing, we have to type a commit message, and click submit commit message
• We may have to highlight the changed/staged files before committing/creating pull request - test this
• Add wording/screenshot for how to preview the full site on a ReadTheDocs from the link in the PR checks

General impressions and ideas

• Definitely need more images of buttons and screens
• Short, animated screenshots would be even better
• Short videos for explaining the different stages/steps in the contribution workflow would be very useful
• Next volunteer: Refine the contributing instructions! (Once we've integrated the current batch of improvements)

[ejaffe-osc]

How To Contribute to NAIRR Community Resources Documentation

1. Make edits in Codespaces (https://github.com/NAIRRProgram/nairr)
   a. Click on Code
   b. Click on ‘Codespaces’ tab
   c. Click on ‘Create new codespace on main’
   d. If prompted to periodically git Fetch, click ‘Yes’.

2. Make changes in Codespaces
   a. Docs are mostly in /docs/source/ - edit existing or create new files
   b. (what file to add/edit, how to name?)
   c. Create new filename parallel to index.rst, eg. ‘featureX.rst’, add content
   d. Add link in index.rst toctree, ‘featureX’ that matches filename

3. Preview local build in Codespaces (builds automatically on changes?)
   a. Codespaces terminal bottom pane
   b. Cd docs
   c. Make html
   d. Cd build/html
   e. Python -mhttp.server, open in browser
   f. Repeat 3c and refresh browser to see new changes.

4. Submit Pull Request in Codespaces
   a. Click ’Github Pull request’ icon (Left-hand, bottom side of VSCode)
   b. # Raising a pull request in Codespaces
   c. Select all modified files.
   d. Commit and Create a pull request
   e. Would you like to stage and commit all your changes? Yes.
   f. Committng to a protected branch and may nott be able to merge changes. Create a new branch
   g. Add commit message, click check mark in top right to accept commit message
   h. # https://docs.github.com/en/codespaces/developing-in-a-codespace/using-github-codespaces-for-pull-requests#opening_a_pull_request_in_codespaces
   i. # delete this # From your fork to NAIRRProgram/nairr ‘main’
   j. Add a meaningful title and description
   k. Create pull request
   l. Publish branch button

5. Once check is successfull, click Show, and Details to see preview RtD preview build