Skip to content

Latest commit

 

History

History
58 lines (41 loc) · 5.12 KB

CONTRIBUTORS.adoc

File metadata and controls

58 lines (41 loc) · 5.12 KB
Raw

Contributor’s guide

Table of Contents

Contributing to documentation

Contributions to documentation can include, but not limited to, creating, updating, and/or reviewing content for the Code Coffee Compendium. We use a docs-as-code approach and the GitHub flow workflow to fascilitate these contributions. To decide what you can contribute, read through the list of Issues and comment on the issue if you’d either like to work on the particular issue or require additional clarity on the issue. Once you decide which issue you’d like to work on, you can submit a pull request. Contributors are also welcome to open an issue as well as help with reviewing a pull request.

Opening an issue

Issues specify tasks that allow maintainers to capture & resolve missing or incorrect content, as well as implement new features or bug fixes in the documentation build tools. Some issues are grouped by Milestones - a collection of issues that relate to a specific deliverable. Completed milestones are tagged as a Release.

To open an issue,

  1. On GitHub, navigate to the Code Coffee Compendium repository and click Issues

  2. Click New issue.

  3. Specify a title for the issue topic. A good issue title should start with a verb, e.g., add tutorial for learning git.

  4. Write a brief description of the scope of the issue, e.g., As a beginner developer learning distributed version control, I want to follow an interactive tutorial for learning git, so that I can manage my project such that I can track, branch, and/or revert changes.

  5. Click Submit new issue.

Submitting a pull request

A pull request is a proposal for changes to a branch.

To submit a pull request,

❗
 If you haven’t been added as a collaborator to the Code Coffee Compendium repo, you will need to either fork the repo or contact the repo admin (@capsulecorplab, @cynful, @sugarsyntax, or @tristandamron) to request write access. If you’ve forked the repo, be sure to sync your forked repo in order to avoid potential merge conflicts.

  1. Create a new branch in the Code Coffee Compendium repo. Make sure the branch name follows the content style guide for naming a branch.

  2. As you edit your content, ensure that it conforms to the content style guide.

  3. Commit your changes and create a pull request. Be sure to include a closing keyword followed by the associated issue number in the pull request description, e.g., closes #1701. If the pull request closes multiple issues, add a closing keyword for each issue.

❗
 If you are creating a pull request from a forked repo, be sure that the base branch of the pull request is set the main branch of the Code Coffee Compendium repo, not your forked repo.

  1. If you’re not yet ready for a review, mark the pull request as Draft to indicate it’s a work in progress. Continue updating your doc and pushing your changes until you’re happy with the content.

  2. When you’re ready for a review, mark the pull request as Ready for review.

  3. Once your pull request has been merged, you can safely delete your branch.

Content style guide

Naming a branch

Branch names should be all lowercase, prepended with its associated issue label, followed by a dash-separated description of the changes to be made, followed by its associated issue number, and delimited by a forward slash, /. e.g., feature/add-tricoder-with-touchscreen-docs/1701. If no such issue exists, open an issue.