|
...
In order to help reviewers (and folks investigating code changes later on e.g. to understand the cause of a bug) understand both why the code needs to change and why / how it was changed in a particular way.:
- A pull request should be submitted when the submitter considers it ready for review (e.g. tests have been written etc)
- A pull request should have a single, clear purpose. This may mean that a single JIRA issue needs one pull request to fully resolve it
- A pull request should have a description briefly explaining why and how the code is changing
- A pull request description may explain the design or approach taken
- Commits messages should explain the intent of the changes in the commit (e.g. please do not use a message like {{working on x feature}} for every commit)
...
In order to understand what changes are in a module version and reduce the effort required to release it.:
- The fix version of the JIRA issue should be updated when a pull request is merged as it takes considerable effort to fill this in later when absent
- At the discretion of the lead maintainer, it may be required that a branch contain updates to the news / change log so that does not need to be done at release time
...
The owner of the pull may choose to merge, squash or rebase the pull request. The most appropriate option should be chosen to aid maintenance in the future (e.g. understanding the change, back porting the changes).
The lead maintainer of the repository may provide guidance limiting these options for a specific repository. Any restriction must be documented in the readme.
The branch should be deleted after a pull request has been merged in order to limit the accumulation of old and redundant branches in a repository
Back end Specific Guidance
...
In order to help communicate and coordinate the impact of interface changes.:
- Any interface change should be reflect in the version in the RAML and the module descriptor
- A breaking compatibility interface change must be merged in coordination with pull requests for dependent modules in order to minimise disruption to the hosted reference environments
- A breaking compatibility interface change should include a major version change to the module implementation version
...