With many people contributing code in parallel it's important that we set out a few rules to ensure consistency in the code base.
Please adhere to these guidelines, PRs and issues that don't will most likely be closed.
Before, during and after working on code, follow these rules for raising and tracking issues.
We take a permissive approach to issue tracking on JIRA - anyone can sign up, and anyone that has signed up can raise new issues.
For bug reports we encourage everything and anything to be raised as it's relatively low cost to label them Won't Fix if they turn out to be bogus.
For stories, it will usually make sense to discuss with the Maintainers first to scope the improvement or feature in question. If the area is very large, ambiguous or contentious, you may be asked to draft a PDP for review first.
Although anyone can create issues, to ensure consistency & traceability over time the main detail (title, etc) of bugs and stories cannot be altered once they've been created - use the discussion facilities in JIRA to refine and clarify issues and work with the Maintainers if you believe the main detail needs to change.
Anyone who has signed up can assign issues to themselves, but it's good practice to discuss assignment with the Maintainers first to ensure what you are about to do aligns with other work that might be in progress.
Please assign an issue to yourself before you do any work on it, otherwise you may find your work clashes with what others are doing, or that the issue is assigned to someone else or closed without warning.
Please discuss issue reassignment with the Maintainers if you feel this is necessary.
Move issues you are working on to "In Progress", otherwise the Maintainers may assume the issue is inactive and disposition it in a way you didn't expect.
Clarify all concept, design and implementation issues using the discussion facilities on the JIRA issue itself. If you have out-of-band discussions, summarize the outcomes on the JIRA issue. In this way, we keep all relevant information about a given issue in one place and maintain a sensible history that anyone can review. For bugs in particular, this will sometimes end in the issue being resolved with "Won't Fix".
Once an issue is resolved to the best of your knowledge, refer to the "GitHub" section below for how to make Pull Requests.
Once you have one or more Pull Requests, add the PR links to a comment on the JIRA issue. This makes it easy for everyone to correlate code changes with the reason they're made.
Once the PRs have been submitted and are awaiting review, move the issue to the "In Review" state. This flags to the Maintainers that it needs attention.
From here, most activity will continue on GitHub as a discussion about the implementation on the PR itself. If and when the corresponding PRs are merged then the Maintainers will move the JIRA issue to "Done" and update any CHANGELOGs as necessary.
git config --global user.name "John Doe"
git config --global user.email firstname.lastname@example.org
Creating a feature or bugfix
Force widget factor to 7
Introduced new WidgetFactorFactory to generate sevens
PNDA-1234: Widget factors other than 7 cause all kinds of problems