Streamline onboarding resources, including Contributor's Guide

[m-miedema]

I'm opening this discussion to revise the Contributor’s Guide to reflect updated resources and practices. We should also consider what accompanying resources we can provide to onboard new and returning contributors!

We have already collected responses to the guide in a survey (thanks to @isesteves and @me-pic) and done some hands-on testing/brainstorming at our spring codesprint. Some general topics that we've discussed so far:

• Structure of a more 'wiki-style' guide
• Whether to remain on physiopy.github.io or move to a readthedocs format
• Providing pathways for different kinds of contributions, including documentation
• How we want to use the project boards (and how to make this clear!)
• What more practical command line tutorials to offer
• Adding flowchart(s) to better conceptualize the issue --> PR --> merge process
• Adding stage-specific to-do lists
• What to include in a main Contributor's Guide vs. guides to contribute to particular packages

We also discussed some practices we could explore to faciliate easier contributes, such as:

• Clearer PR requirements, such as including specific requests/expectations for reviewers
• Library teams/maintainers
• Library-specific project boards
• Different repo permission practices, including 'triage'
• Making documentation testing required (if it exists for that repo)
• Automation (e.g. with issue/PR labels/assignments)
• Where to track contributions that may not obviously fall into an existing Github repo, especially if we want to open a corresponding issue for them (e.g. for use on a project board)

Thank you to everyone who has contributed to the discussion so far! In particular, everyone who brought suggestions and feedback during the codesprint: @RayStick @rgbayrak @me-pic @beccaclements99 @goodalse2019 @smoia

[m-miedema]

We have a main reviewer checklist IPR here to be incorporated: https://github.com/physiopy/phys2bids/pull/316/files

[m-miedema]

@rgbayrak you mentioned looking into readthedocs or other github.io templates at the codesprint, did you have a change to follow up on this?

[m-miedema]

@me-pic has opened an issue which should provide a good compromise between better organization and minimal re-tooling of the website! #55

[m-miedema]

#17 this is a good point!

[m-miedema]

#59 will help to include here as well, although I've made some preliminary passes at discussion in the guide itself at #58

[me-pic]

Following the point about more practical command line tutorials to offer, I think one point that is missing right now is to show the steps for reviewing PRs. Maybe having something like:

git remote add <remote_name> <ssh link>
git fetch <remote_name>
git checkout <name_of_the_branch>

I think being more specific on what git commands to use would make the contribution process a bit more easier, since it seems that this is a big limitation to contributing.

[rgbayrak]

@rgbayrak you mentioned looking into readthedocs or other github.io templates at the codesprint, did you have a change to follow up on this?

Yes! How about > https://github.com/alshedivat/al-folio? Very modern, great utility.

We can have various tabs including documentation, presentations/poster, tutorials/youtube walkthroughs, publications, repos linked. Updates/news on the landing page.

[m-miedema]

@rgbayrak you mentioned looking into readthedocs or other github.io templates at the codesprint, did you have a change to follow up on this?

Yes! How about > https://github.com/alshedivat/al-folio? Very modern, great utility.

We can have various tabs including documentation, presentations/poster, tutorials/youtube walkthroughs, publications, repos linked. Updates/news on the landing page.

Thanks @rgbayrak! I think for now we've got the template in place after the work @me-pic did in the hackathon last month, we did a brief tour at our community meeting on Thursday. Should be merged to the website soon!