Skip to end of banner
Go to start of banner

Pull Request Guidelines

Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 10 Next »

Status

IN PROGRESS

Stakeholders

All developers

Outcome
Created date

  

Owner

Marc Johnson Zak Burke


This guide is intended to provide guidance of how pull requests for community maintained modules should be managed.

Minimum Expectations

  • A pull request must be related to a JIRA issue in the appropriate project for that repository
  • A pull request must include a reference to the JIRA issue in the initial title

These are both necessary in order to relate code changes to why the code needed to change (see below)

Expanded Guidance

Relating code changes to why the change is needed

In order to understand what caused a code change to be made, it is important to be able to relate changes to the reason the code is being changed. This is especially useful especially when finding the code to back-port a bug fix or for investigating the cause of a bug.

It is also useful for setting some context for the changes for reviewers and for tracking which code changes are included in a module release (via the fix version in JIRA, see below).

  • A pull request must be related to a JIRA issue in the appropriate project for that repository
  • A pull request must include a reference JIRA issue in the initial title
  • A branch name should include a reference to the JIRA issue
  • Commits may include a reference to the JIRA issue

Sharing the intent of the changes

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)

Release Management

In order to reduce the effort required to release a module version.

  • 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
  • A branch should not use SNAPSHOT versions of maven dependencies as module versions should be released with provisional dependencies

Merging the Pull Request

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.

References

The use of must, should, may etc is based upon RFC2119

More thoughts can be found for good commit messages at https://chris.beams.io/posts/git-commit/ (taken from the existing documentation at https://dev.folio.org/guidelines/contributing/ )

  • No labels