T4.1 Build out the contribution guide

[codytodonnell]

To Do

• [x] look for contrib guides for related/similar projects
• [x] look for contrib guides known to be good
• [ ] keep notes on the directory structure of those projects
• [ ] look for advice on contrib guides
• [ ] look for contrib guides for design projects
• [ ] think of the kinds of contributions we would have

[jlcohoon]

In workplan: Define contribution processes and partnership structures for STRUDEL as an open source projec

[jlcohoon]

• Cody wrote a contribution guide for tutorial goers to be able to contribute back if they're inspired
• Want to have instructions on every option for contribution (what are those?)

• adding a feature, fixing a bug, adding a new task flow (how can that be broken down further? propose a design, contribute a design, code the actual task flow), contribute to docs, contribute to a tutorial (which would be a docs contribution?)

• Tabler/all contributors guide will be a good place to start looking (https://github.com/tabler/tabler/tree/dev, https://allcontributors.org/)

• How detailed should we be? Instructions on forking? Style info?
• How do we want people to actually do this work? open an issue? write something up elsewhere? just go ahead?
• Contributors might be

• tutorial goers

• collaborators

• who else?

• Should we have a contribution tutorial? (Georgia suggested this)
• Should we get involved with students? that would be a good way to get contributors
• Need to be thinking about how to shepherd contributions toward something e want done
• Need to think about how to help people see where they can contribute easily
• Want to be providing credit -- All Contributors can be a way to do this, especially since GH only considers lines of code as contributions
• Cody brings up the possibility of separating the templates, CLI, cookie cutter cutter folders into separate repos as a way to make things more comprehensible to a newcomer. Is that a good idea? We don't know yet but will keep notes on how the projects we research do this. Cody will also talk about it in a dev meeting.

To dos added to top comment, to be done by next Fri:

• look for contrib guides for related/similar projects
• look for contrib guides known to be good
• look for advice on contrib guides
• look for contrib guides for design projects
• think of the kinds of contributions we would have

We will work in GH. To edit the guide, create a feature branch. To gather notes or discuss progress, leave a comment on this issue. Can write doc sections here first, if preferred.

[codytodonnell]

Examples of contributor guides:

• shopify-cli
  • They have a few interesting sub pages that we may want to include like, Conventions, Testing Strategy, Decision Records etc.
• material-ui
  • MUI's guide is also good and has more examples of more operational parts of contributing (PRs, issues, getting accepted, etc.)
• numpy
  • Another very thorough guide to contributing, touching on both development and other methods

[jlcohoon]

Things to talk about:

1. what we (don't) like about the examples
2. ways to contribute
3. specificity of instructions
4. where info is/difference between locations
5. how are contributions motivated
6. how are contributions rewarded/recognized
7. repo structures

Some additional examples

• Storybook -- README -- CONTRIBUTING.md
• Carpentries -- Get involved
• Node.js -- CONTRIBUTING.md -- website contributing page
• Orbit -- README -- CONTRIBUTING.md -- when talking about repo structures: https://orbit.kiwi/getting-started/github/
• Parsl -- CONTRIBUTING
• Dribbble

[jlcohoon]

1. what we (don't) like about the examples
2. ways to contribute
3. specificity of instructions
4. where info is/difference between locations
5. how are contributions motivated
6. how are contributions rewarded/recognized
7. repo structures

Shopify CLI

• CLI kit & have templates related to design system
• like that there are subpages on contributing (getting started, conventions, performance, etc.)
• detailed content
• decision records explain why they made certain changes; could be useful to do as well (but then brings up how we make decisions ourselves)
• distinguishes in instructions between extending and creating something new; poses questions to help you decide what to do
• have separate instructions for CLI tool and UI kit

Material UI

• one page, kind of short
• starts with making a pull request but does acknowledge doc improvements, financial support, feedback as other ways to contribute (https://mui.com/material-ui/getting-started/faq/#mui-is-awesome-how-can-i-support-the-project) -- we will also want a way for people to provide feedback (anonymously?); easy ways to give feedback are good onboarding mechanisms
• have content on how to make sure your change will be accepted -- how do we balance this with seeming open to contributions?
• doesn't seem to discuss conceptually what kinds of contributions can be made
• like that they have info on how to make a PR

Numpy

• on their website
• very detailed
• includes lots of ways to contribute: translation, fundraising, code maintenance, etc.
• don't do "good first issue" but instead have "sprintable" issues
• some content on dev process like starting a dev environment is repeated elsewhere in their docs but because it doesn't change much that's likely okay to repeat (but also you have to update those places?)
• they have info for packages dependent on them

[codytodonnell]

Storybook

• Explicitly say that PRs and stars are welcome. We could explicitly state that stars are a valuable metric for us.
• Use the "good first issue" tag
• It would be good to post our affiliated organizations in the readme
• Contributor guide is coder centric
• New guide starts with their code of conduct
• Sub guides for each way to contribute. Some are more instructional than others.

Carpentries

• Get Involved page directs to how to contribute
• "You belong here!"
• Various roles and ways to get involved

NodeJS

• Developer's Certificate: what a developer is agreeing to by contributing
• Not a ton of info on the top level page but links to sub pages
• Extensive docs for each topic in its own file
• Linking out could be simplest way not to repeat info

Orbit

• Components and patterns
• Patterns are really text based documentation on design patterns and guidelines
• Contribution section in the main readme, links out to full contributor guide
• Issue template and feature request template

Parsl

• Use the "help wanted" tag for issues
• Development process (forking and making a PR)

Dribbble

• Contributing design images
• Each piece of work is a "shot"
• Uploading images, tagging images, "Looking for feedback?", Publish now