GitHub conventions and workflow for Carbon LDP

Miguel Aragón edited this page May 30, 2018 · 5 revisions

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

Where to Open Issues

Several GitHub repositories can be found in the CarbonLDP organization. Ideally, we like to have issues opened against the repository that is most appropriate to the given issue. In some cases, however, you may not know which repository is most appropriate. For that reason, we have established this general repository for instructional wiki pages (like this one) and for general or unclassified issues. If you are pretty sure you know which repo your issue pertains to, post the issue in that repo. If you are in doubt about which repo your issue pertains to, post it here.

After posting an issue here, our staff will likely open a duplicate issue in the appropriate repository. We will then post a comment to the issue that references the duplicate and close the original. That is to say, we will move the issue to the appropriate repository by way of duplication.

New Issue Requirements for the User Community

Carbon LDP users should not concern themselves with issue labels, milestones, or assignees. 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.
  • Provide a brief, but descriptive (non-ambiguous) title.
  • Provide comments and screenshots describing the issue in greater detail. If reporting a platform issue, please provide the platform version from your Carbon LDP server, which can be obtained from your server at the following URL: <host>/platform/api/.

Issue Processing Workflow for Carbon LDP Staff

Classify and Optionally Prioritize the Issue

After a new issue has been opened, Carbon LDP staff may process and manage the issue using the following workflow.

Identify the correct repo for the issue and if necessary, move it by creating a duplicate issue in the appropriate repository. Add a comment to the original issue, which links to the new duplicate following this convention as an example:

This issue corresponds to carbonldp-panel because it's actually a component of document-explorer module which lives inside that project.

Moved to CarbonLDP/carbonldp-panel#11

Note that the hyperlink is created automatically by GitHub just by adding the reference to /# in your comment.

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: question - any question seeking answer by community or product staff
  • type: suggestion - a feature request or wish-list item
  • type: task - a general activity to be done (a TO DO)

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

Carbon LDP 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 staff member, 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:

  • TODO - issues are prioritized and selected for the near-term work period
  • In Development - issues are assigned and actively being worked by the assignee
  • Pending Review - active work is assumed complete, a pull request has been made, and the issue has been reassigned to reviewer
  • Pending Release - the pull request has been reviewed, approved, merged and is pending deployment
  • Done - the results of the resolved issue exist in released product

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
  • status: question - the issue cannot be resolved until a pending question (in comment) is answered

Branch and Pull Request Requirements for Carbon LDP Staff

Branching and Branch Naming Conventions

  • Before active development on an assigned issue, staff must create a new branch. Issues are never addressed in the develop or master branch; they are only merged there after review and approval.
  • 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_miguelaraco.

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.

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 because this is typically what will be used to update the CHANGELOG when the change is released.

    • CHANGELOG style needs to be in bullet-list form (can be nested).
    • If the change complete's a feature or task, you should write Complete #<issue-number>. For example, Complete #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 need to MUST state them. For example: ### Breaking Changes (then a bulleted list of the breaking changes).
    • At the end of the day, this pull request message is for the benefit of the user and so you need to wear that hat when composing the commit comment. What is essential or helpful for the user to know?
  • DON'T CHANGE CHANGELOG.md yourself. The project's maintainer will update that file before releasing a new version (which normally includes several pull requests).

Reviewing and Rejecting or Merging a Pull Request

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

  • 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.
Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.