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.
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.
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."
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.
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.
Once you have your own fork of a repository, you will need to clone that repository locally to your own machine.
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".
Clicking the "Clone Repository" button will provide a dropdown where you can specify the location of the remote repository.
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.
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.
git remote add upstream <repository url>Adding a remote in VS Code is done by:
-
Clicking the ellipsis menu on the ending right side of the cloned repository.
-
Navigating to the "Remote" section.
-
Clicking on the "Add Remote…" menu entry
You will then be presented with a similar dropdown to supply a repository name and URL as when you originally cloned.
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.
|
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.
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:
Once selected, you will be prompted with a menu to select which configured remotes you would like to use:
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:
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.
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.
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.
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>