Contribution workflow

[TangoYankee]

Create Issue and PR templates. The concept is to standardize the workflow of identifying issues, discussing solutions, and implementing code. It should slow down coding and speed up development.

[theecrit]

Documenting a potential Issue template here until I get everything up and running locally and can properly do a branch and PR. (Note: "platform/dev environment" option could probably be phrased more appropriately.)

Please open an Issue for bugs only.
New feature requests should be filed as a card in the appropriate Trello backlog.

• Expected behavior:
• Actual behavior:
• Reproduced how many times?
• Steps to reproduce:
• Your platform/dev environment:
• Possible cause and/or recommended fix, if appropriate:

[TangoYankee]

Please open an Issue for bugs only.

The trello board is too cumbersome and confusing for detailed technical discussions. I agree that large scope ideas need to be documented in the Trello, to keep the whole informed. I integrated that into the initial guidance I posted to Slack. However, fine-grained discussions need to move to GitHub, regardless of whether they are bugs or features.

[theecrit]

Should we update this issue to cover only the PR template, given that we just addressed the Issue template in 53?

[TangoYankee]

@theecrit, yes. Adding comments to the chain, rather than editing earlier posts, is probably better. This way, we keep the history of changes.

[TangoYankee]

Issues templates are resolved and merged. We are using the GitHub Defaults
For Pull Requests:

• Link it to an issue and/or describe problem addressed and method used to solve it
  • Make pull requests based on issues that have already been discussed. This means that the solution has already been vetted. Discussions in the Pull Request can focus on code implementation.
• To the maximum extent possible, focus pull requests on one bug or feature. This decomposes complex problems into easier to understand parts. This accelerates review and implementation.
• Pass given tests. Or, provide justification for test failure to reviewer and outline steps to mitigate failure.
  • If you are failing tests, please try to resolve the issue before asking for a review. Of course, if you need help resolving the issue, we are happy to help
• Request Review from Contributors
• Leave Pull Request Open for at least 24 hrs. As a volunteer project, contributors may not be able to immediately make comments. Adding a slight delay allows for multiple reviewers to provide input. If this proves to be too long or short, we can adjust the time frame. The intent is to balance being delayed too long with moving too fast.
• Address code comments and make appropriate changes
• Merge pull request

[theecrit]

Looks great. Two questions:

1. Should we extend the length of time a PR should remain open? I've noticed that folks often need at least a couple of days. Maybe 48 hours would be a little more contributor-friendly?

2. Do we need to set a minimum number of reviewers to request? Not sure if there's a best practice/standard here.

Thanks!

[TangoYankee]

Split the difference and call it 36 hrs? Again, we can always evolve if it seems necessary.

I've thought about increasing the number of reviewers. If this was a paid project, yes. However, a volunteer project is less predictable. One mandatory review is fine. Any more and we tie our hands.

[theecrit]

@TangoYankee Works for me. What’s required to close this issue? Where do we want to document this? Should it go in a contributing doc?

[TangoYankee]

I would like to expand this issue to include the general workflow to contribute. This includes

• Issues Templates
• Labels to track the status of issues
  • Required: Status (backlog, discussing, implementing)
  • Required: Bug (if bug...obviously)
  • Optional: topic, such as backend, frontend, accessibility, etc (if not bug)
• Pull Request Template
  • Current Conception
• Community Standards/Code of Conduct
  - Open Oakland Code of Conduct and/or
  - Contributor Convenant, with email address: safespace@openoakland.org
• Contributing.md
  • Write permissions
    • Request permissions in-person, at Open Oakland meetup
    • Contributors without a code review, discussion in issues, or commit in past 60 days will have write permissions revoked. Write permissions may be retrieved by contacting Timothy Miller at miller.tim108@gmail.com
  • Google Doc Overview
  • Trello Board
  • GitHub Issues
    • Note about security related issues being restricted to email and slack
  • Wireframes
  • PR Process
  • Python/Django Code Standards
    • Pylint settings found in pylintrc
    • Generally follow PEP 8 standards
    • Docstrings follow Numpy Style
  • Template name and structure

[theecrit]

Looks great. Re: labels — we can use labels to track status (e.g. In discussion/Needs input/Ready to work on/In progress), or we can we use them to track topic (e.g. Feature request/Accessibility/Bug/Good First Issue...). Or, theoretically, both.

[TangoYankee]

@TangoYankee Works for me. What’s required to close this issue? Where do we want to document this? Should it go in a contributing doc?

There will be a Pull Request with all of the changes proposed in this Issue. Once that Pull Request is merged into the code base, this Issue will be closed.