T4.1 Build out the contribution guide

[codytodonnell]

To Do

• look for contrib guides for related/similar projects
• 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
• outline contrib guide in a Google Doc

[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

[jlcohoon]

Having talked through these examples with @codytodonnell on 30 Oct, we're going to move on to outlining a contribution guide in Google Docs. We'll meet next Friday to discuss further. Still need to look up some guidance on contributor guide best practices. Adding the Google Doc outline to our tasks list up top

[jlcohoon]

Discussing our progress toward a contributor guide:

• moving between a discussion and an issue has multiple possible routes — trying to anticipate our own and users' needs is tricky
• if we create an issue from a discussion, what happens? We tried it out and the discussion stays active and a new issue says "Discussed in ###". This is the simplest way to create an issue with provenance but it means the issue is created in the strudel kit repo automatically. Is that okay? Cody is thinking yes. You can transfer issues between repos so it's not like it's permanent
• -> we'll pick a preferred route for the contributor guide but it won't really matter
• do we want people to open a new thread when they want a new task flow or should there be one discussion place for them all? We're thinking that until discussions get so full that they're difficult to keep track of, having a place labeled as "new task flows here!" could evoke more discussion than an empty forum.
• -> you can reply to other's comments in the discussion thread, so theoretically each new task flow could be a high level comment with replies below
• -> we will propose "create issue from discussion" as the easiest way
• something we learned is that the top level comment in a discussion populates the text input field when you "create issue from discussion"
• proposing a task flow probably comes before designing one
• mechanics of issues/discussions can be in one section but what content you would provide can be elaborated on in guide sections like "proposing a new task flow"
• How do we ensure that the quality of contributions meets our UX standard?
  ---> in STRUDEL sync we talked about other people helping us evaluate these and how we'll need to set up governance mechanisms

other thoughts:

• in a workshop, maybe we have people make a contribution or leave a comment of some kind