GitHub Conventions and Workflow

We use GitHub to host our git repositories and track project issues (e.g. bugs, features, questions, suggestions, tasks).

This page describes the conventions we use and the workflow we follow. It is intended for both our community of users and for our professional staff.

Posting New Issues

Rock Mountain users should not concern themselves with issue labels, milestones, or assignees. In this repository we have included some issue templates to ease your issue reporting process. To open a new issue:

• Navigate to the repository the issue pertains to, or this one if you are unsure.

• Click on the Issues tab.

• Click the New Issue button.

• If available, select the template that best accommodates your needs, and fill the corresponding sections.

• Provide a brief, but descriptive (non-ambiguous) title.

• Provide comments and screenshots describing the issue in greater detail. Please provide the platform version which can be obtained from the footer of your site.

Issue Processing Workflow for Rock Mountain Developers

Classify and Optionally Prioritize the Issue

After a new issue has been opened, Rock Mountain developers may process and manage the issue using the following workflow.

Identify and label the issue type. Following are the options:

• type: bug - a software defect (assumed or verified)

• type: feature - a task related to an existing, approved, or in-process feature

• type: suggestion - a feature request or wish-list item

• type: task - a general activity to be done (a TO DO)

Note: Issues of type: question should not be issues, but rather, should go into the GitHub Discussions tab. This hasn't been verified, but I think tagging an issue with question or discussion automatically sends it into the Discussions area.

If the type is type: bug, add a bug clarifier label; one of:

• bug: can't reproduce - an attempt to reproduce the issue has failed; more information is needed

• bug: verified - reproduced or verified as a system defect

• bug: needs verification - the bug still needs to be reproduced or verified as a valid system defect

Rock Mountain staff may assign a priority label to the issue at any time. This does not mean that the issue has been accepted or become active. A priority label may alternatively be applied when the issue is assigned to a developer, which means that the issue has been accepted for active work. Following are the priority options:

• priority0: critical - the issue should be addressed as immediately as possible

• priority1: urgent - the issue should be addressed within the current work phase

• priority2: required - the issue needs to be addressed as time and resources can afford

• priority3: nice-to-have - the issue would provide an improvement, but is considered trivial to the higher priorities

Review, Assign, and Resolve Issues

Each repository has a Kanban Board, which can be found under the Projects tab in the respective repo on GitHub. The workflow columns on the Kanban Board are the same for each repository:

• To Do - issues are prioritized and selected for the near-term work period

• In progress - issues are assigned and actively being worked by the assignee

• Done - the pull request has been reviewed, approved, merged, deployed, and the results of the resolved issue exist in released product

For now, we just use the Basic template when creating new kanban boards.

During the lifecycle of an issue (within the Kanban workflow), status may be tracked with the following labels:

• status: blocked - the issue cannot currently be resolved because it is blocked by some dependency

• status: help needed - the assignee is struggling to resolve the issue and needs more information or staff assistance

• status: needs more work - work on the issue has been deemed unsatisfactory by reviewer and pushed back in the workflow for additional work

• status: needs update - the issue has either been reviewed, but cannot be merged or cannot be reviewed until the related branch has been updated to the latest state of the main branch

Branch and Pull Request Requirements

Branching and Branch Naming Conventions

Before active development on an assigned issue, developers must create a new branch. Issues are never addressed in the preview or main branches; they are only merged there for review and approval (preview) and then deployment to production (main).

The branch names must adhere to the following naming convention: <type (feature,bug,task)>/#<issue-number>_<optional-clarifying-short-description>_<optional-developer-name>. For example: feature/#12_update-angular. Or, when an issue is big enough to have multiple developers: feature/#12_update-angular_johndoe.

Committing Code

• When committing code, follow the conventions described in How to Write a Git Commit Message.
• Each commit should be a single logical change. Don't make several logical changes in one commit. For example, if a patch fixes a bug and optimizes the performance of a feature, split it into two separate commits.

• Don't split a single logical change into several commits. For example, the implementation of a feature and the corresponding tests should be in the same commit.

• Commit early and often. Small, self-contained commits are easier to understand and revert when something goes wrong.

• Commits should be ordered logically. For example, if commit X depends on changes done in commit Y, then commit Y should come before commit X.

Updating the CHANGELOG

When creating a Pull Request that will affect final users, be sure you have modified the CHANGELOG.md file. For this use the following CHANGELOG style for clarity purposes:

• CHANGELOG style needs to be in bullet-list form (can be nested).

• Use capital letters to start each bullet point.

• Don't use periods at the end of each bullet point.

• Remember to maintain the UNRELEASED header. The project's maintainer will update that header before releasing a new version (which normally includes several messages).

• Include your change in the corresponding header, depending on what you did:

  • For added features list your message under the Added header and describe what users can now do.

  • For bug fixes list your message under the Fixed header and describe the unexpected behavior that got corrected.

  • For breaking changes list your message under the Breaking Changes header and add an explanation of what features no longer exist/work and describe the new way of making things.

• Beware of maintaining a consistent ordering in the headers. (Added/Fixed/Breaking Changes).

• Link the issue your change is related to at the beginning of your message.

• Sort the messages included in the CHANGELOG using the issue number; from largest (most recent) to smallest.

A sample CHANGELOG message should look as follows:

FIXED #13 - Broken License link in website

At the end of the day, this CHANGELOG message is for the benefit of the user and so you need to wear that hat when composing it. What is essential or helpful for the user to know?

Making a Pull Request

When you issue a pull request, you need to fill out:

• Title - The first thing in the title should be a reference to the related issue, followed by a short description. For example: "feature/20 - Add encryption to ..."

• Comment - The comment should be a markdown summary list of the resulting changes that users can expect as part of the subsequent merge. You should do this in CHANGELOG style for clarity purposes.

CHANGELOG style needs to be in bullet-list form (can be nested).

• If the change complete's a feature or task, you should write Resolve #<issue-number>. For example, Resolve #32. By doing this, GitHub will automatically close the issue when the pull request is merged.

• If the change resolves a bug, you should write Fix #<issue-number>. For example, Fix #33. Again, GitHub will automatically close the issue when the pull request is merged.

• Use capital letters to start each bullet point.

• Don't use periods at the end of each bullet point.

• If your pull request introduces breaking changes (especially if you are in an API related project), you MUST state them. For example: ### Breaking Changes (then a bulleted list of the breaking changes).

Bear in mind that all pull requests must be related to a corresponding issue. Otherwise, reviewers will reject the pull request.

Reviewing and Rejecting or Merging a Pull Request

All pull requests are reviewed by a peer before being merged back into a main branch.

• All pull requests that are not related to an issue must be rejected.

• The reviewer should post comments inline of code within the GitHub Files Changed tab in the pull request.

• When an inline comment is made, the reviewer should click the Start a Review button on the comment, which establishes a review session or state under which multiple comments can be made.

• When done, you can choose Comment, Approve, Request changes and leave a summary comment.

• Steps for merging may be project-specific.