Skip to content

Latest commit

 

History

History
175 lines (119 loc) · 8.1 KB

CONTRIBUTING.adoc

File metadata and controls

175 lines (119 loc) · 8.1 KB

Contributing Guide

The documentation found in this repository is written in Asciidoc. While many tools will work with Asciidoc, as it is purely text, the recommended setup can be done using only VS Code and a small set of extensions. Below, you will find the recommended setup, as well as some conventions that are being used in this repository.

Tool Setup

Visual Studio Code (available at https://code.visualstudio.com), known colloquially as VS Code, is a simple code editor. On its own, it will work fine, however, you can improve your experience by adding the Asciidoc extension. Adding this extension will provide you with syntax highlighting, live preview, and snippets.

AsciiDoc VS Code Extension
Figure 1. VS Code AsciiDoc extension

This extension can be installed by visiting https://marketplace.visualstudio.com/items?itemName=asciidoctor.asciidoctor-vscode, by using the "Quick Open" and pasting ext install asciidoctor.asciidoctor-vscode, or by using the built-in extension browser within VS Code.

There are other extensions which can provide additional insight or aid in the contribution process, but they are not required. These extensions are "GitHub Pull Requests and Issues" and "GitLens." Of those two, "GitHub Pull Requests" is more helpful than "GitLens."

Git Workflow

The BAMOE Documentation in this repository utilizes feature or topic branches for work. You can read more about those at Git feature branch workflow by Atlassian and Branching Workflows on the main git website.

Essentially, this means all work should be done on its own feature branch. The quick and dirty way of doing this is to simply create a new git branch from the main (or other version branch i.e. 9.x, 10.x, etc.). On the command line, this can be accomplished by running git checkout <base branch name> followed by git checkout -b <name of new branch>. Other tools have different ways of create a branch. Later in this guide, the way of doing this using VS Code will be explained and demonstrated.

Forking

The main repository, ibm/bamoe-docs on GitHub, must first be forked to your own GitHub account so Pull Requests (pr) can be made from your fork of the original repository. The method of doing so can be found on the GitHub Docs website.

Cloning Locally

Once you have your own fork of a repository, you will need to clone that repository locally to your own machine.

Cloning a repository locally via CLI
git clone <git repository URL>

Using VS Code, selecting the Source Control section on the left will present two buttons "Open Folder" and "Clone Repository".

Cloning Button VS Code
Figure 2. VS Code Clone Button within Source Control

Clicking the "Clone Repository" button will provide a dropdown where you can specify the location of the remote repository.

Remote Repository Clone Dropdown
Figure 3. VS Code Remote Repository Dropdown

It is highly recommended to add the upstream, the original repository, to your list of git remotes and periodically merging (or pull) changes from that repository into your local copy. The process of performing a merge is detailed later in this documentation.

Adding a remote

The standard convention for git is to call the first repository cloned origin. The origin in this guide will be your own fork. This name can be changed, however, it is out of the scope for this contributing guide. The second repository that should be added to your local repository is called upstream. This should be the ibm/bamoe-docs repository.

Adding a remote via CLI
git remote add upstream <repository url>

Adding a remote in VS Code is done by:

  1. Clicking the ellipsis menu on the ending right side of the cloned repository.

  2. Navigating to the "Remote" section.

  3. Clicking on the "Add Remote…​" menu entry

vscode repo add remote
Figure 4. VS Code Adding a Remote repository

You will then be presented with a similar dropdown to supply a repository name and URL as when you originally cloned.

vscode repo add remote dialog
Figure 5. VS Code Add remote dialog

When working within VS Code, it is recommended to have VS Code periodically sync or fetch the upstream repository so your local copy is kept up to date.

vscode repo git fetch
Figure 6. VS Code periodically running git fetch

Rebase

Warning

Rebasing should ONLY be performed on your own feature branches and ONLY before a pull request has been submitted. NEVER after a pull request has been created.

Rebasing is essentially taking your changes in a branch, saving them, merging something new into the branch, then applying those same changes on top of the merge. It creates different commits and commit ids and can really mess with history of published branches. For simplicity both for yourself and others, don’t use rebasing. A preferred alternative is to merge the other branch into your feature branch and push the whole thing together in one pull request.

Pushing

Publishing, or pushing, a branch is the process of making it available on a different remote. Typically, that would GitHub, however, it could be any other remote. The process is very simply from the command line:

git push <remote name> <branch name>

If you wish to set the upstream for the branch to the remote branch, use the --set-upstream option.

Within VS Code, this is done using the Source Repo → Branch → Publish Branch menu item, as shown:

Publishing a Branch
Figure 7. Publish a branch in VS Code

Once selected, you will be prompted with a menu to select which configured remotes you would like to use:

Select a configured remote
Figure 8. Publish to a defined remote

Pull Request

Pull requests are often done in the browser for GitHub. Read more about creating a pull request in the documentation.

You may also install the "GitHub Pull Requests and Issues" extension for VS Code:

Pull Request Extension
Figure 9. GitHub Pull Request and Issues Extension

This extension will add a new icon on the left side, the GitHub logo, it also allows you to create new pull requests and work with GitHub Issues without leaving VS Code.

Creating a new pull request is done by selecting the GitHub Icon on the left and clicking the "Create Pull Request" button at the top.

vscode github create pr menu
Figure 10. Create a new Pull Request

You can then select the base, the remote and branch, you want to merge into, and the branch that has been published. You should also create a title and description for the pull request.

Pull Request details
Figure 11. Pull Request details

Merging

Merging and pulling within VS Code are synonymous. However, within the command line, a pull is actually a fetch and a merge. Within VS Code, your main branch should already be configured to periodically be synced with the upstream. Should you need to merge some other remote branch into your working local branch, this can be done using the Source Repo → Pull menu.

Pull menu
Figure 12. VS Code Source Repo Pull menu

This will pull from whichever remote branch is set as the upstream. If the "Pull from…​" menu is selected, you will be presented with the familiar dialog to select a remote branch to pull and merge.

On the command line, this action is done using:

git pull <remote name> <branch name>

Conventions