Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
GitHub conventions and workflow for Carbon LDP
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:
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
masterbranch; 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:
- 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 Reviewbutton 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.