Skip to content
This repository has been archived by the owner on May 23, 2023. It is now read-only.

Pull Request and Commit Message Guidelines

Jump to bottom
Chris Bethune edited this page Jan 27, 2015 · 4 revisions

Pull Request

Pull Request logs on GitHub are used to generate the change log, and provide historical records of the changes made to the system. To that end, we standardize the information we include to simplify parsing and provide baseline change detail.

Format

The format is as follows:

PR Subject:

short description

PR Description:

detailed description

(Fixes|Refs) #issue

Each PR should also have a type and category label applied. More below.

Subject:

One line overview of the changes the PR encompasses. Will be extracted into the change log so should be structured with that in mind.

Description:

Expands on the subject, providing the context for the commits associated with the PR. This section should also reference any PRs and issues that are relevant beyond that included in the subject, again using appropriate formatting.

Issue Reference(s)

An optional field capturing the issue(s) this PR addresses, formatted such that GitHub recognizes them as links (see https://guides.github.com/features/mastering-markdown/#GitHub-flavored-markdown). The issue should be prepended by fixes, which will also close the issue, or refs which allows the issue to be referenced but remain unclosed.

Labels

Standard labels have been defined to provide detail used when creating the change log. They fall into two categories - TYPE an COMPONENT. ONE of each category should be applied to a PR.

Type

The type captures the nature of the change:

  • feature - new features not already present
  • fix - fixes to already present features
  • doc - documentation changes
  • style - formatting, missing semi colons, etc.
  • refactor - code cleanup
  • test - adding / updating tests
  • maintenance - general maintenance tasks

Component

The component is the portion of the software a given change impacts:

  • server - tile server and libraries
  • client - client side libraries and application code
  • tiling - tile generation code
  • examples - example source code
  • build - build system / deployment code

Other Tags

Tags to add additional information not capture by type or component.

  • NOLOG - never included in any logs

Examples

Subject:

GPU rendered heatmap support

Description:

refs #4934```

*labelled with Server, Feature*

***

Subject:

```Remove redundant avg range check```

Description:

```Removes a redundant range check from the average double analytic.  This wasn't impacting performance in any noticeable way, but was unneccesary clutter.
fixes #1001```

*labelled with Tiling, Fix, NOLOG*

## Commit Messages

Git convention is to format messages as such:
```

Subject:

One line description of change suitable for display via git log. Suggested soft limit of 50 characters since that is what git log will display without truncating, and many other tools are built around this assumption.

Description:

Multiline. Details providing motivation for change, contrasts with previous behavior. Should include references back to relevant issues using appropriate GitHub linking markdown syntax.

Example:

remove log message generating exceptions

Refs #1863. Debug logs referencing legend contents generate exceptions due to a 
race condition tied to legend state fetch latency.  Moving the logs to the receiving 
handler dumps state but doesn’t cause exceptions.
Clone this wiki locally