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.

JIRA

Before, during and after working on code, follow these rules for raising and tracking issues.

Raising 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.

Assigning issues

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.

Lifecycle

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.

GitHub

Once working on code, follow these rules for working with GitHub and submitting changes.

Before you start

1. Ensure you are in agreement with the terms of submissions at http://pnda.io/pages/docs/PNDA_Project_a_Series_of_LF_Projects_LLC__Technical_Charter_FINAL.pdf and especially the section on Intellectual Property Policy (we are currently in discussion with the Linux Foundation on removing the Contribution License Agreement requirement)
   
   
2. Make sure your git client reflects your name and email address as per your GitHub account
   

      git config --global user.name "John Doe"
      git config --global user.email johndoe@example.com

Creating a feature or bugfix

1. Fork the repository
2. Make sure your develop branch is fully up to date with the upstream
3. Branch from the head of the develop branch
4. Name your branch according to the JIRA issue that caused you to create it
5. Make your changes, commit/push
6. If develop moves on, rebase your branch on develop. Do not merge develop to the branch. 

Submitting a feature or bugfix

1. When ready, rebase your branch in interactive mode and squash all the commits to one commit
2. Make sure the commit message in the one commit -
   1. Is written in the present tense and imperative mood e.g. "Force widget factor to 7" 
   2. Don't exceed 50 characters for the first line
   3. Leave the second line blank
   4. Optionally, on the third and subsequent lines, include any other descriptive text you feel qualifies the reason for the change
   5. Optionally, include a reference (not a URL) to the issue that caused you to make this change e.g. PNDA-8
   6. Push this to your branch and open a PR
3. GitHub will take the title of the commit as the PR name, do not modify this
4. In the description, include any descriptive text you feel qualifies the reason for the change
5. Note validation that has been carried out
6. Do not fill the description with design discussion and so on - describe the code and what it does

 Commit example

       Force widget factor to 7

       Introduced new WidgetFactorFactory to generate sevens

       PNDA-1234: Widget factors other than 7 cause all kinds of problems

Responding to feedback on the PR

1. Keep discussion on the PR if possible and record outcome of side discussions if not
2. If the PR has been closed, do not delete or rebase your branch before re-opening the PR
3. Do not close PRs and open new PRs for the same work
4. Ensure the PR commit history and relationship with develop remains sane
   1. If develop moves on, rebase branch on develop
   2. If rework of existing changes is required it usually makes sense to rebase and squash to one commit
   3. If the additional work is purely additive, an additional commit is often all that's necessary

Changelogs

Given the difficulty of n-way merging on a single location in a single file on GitHub, modifications to the CHANGELOG are a Committer activity. Therefore, omit these from the PR and the Committer will make the CHANGELOG entry after merging.