Working with GitHub repos

There are a large number of GitHub repositories in the TritonDataCenter organisation including one for the content of this documentation site, the main tritondatacenter.com website, our software, and various others.

This guide can be used to better understand proper etiquette for contributing, while also (to the best of our ability) keeping people from stepping over each other's work.

Using git and GitHub

To use GitHub locally via the commandline, install git. There's a quick gittutorial to help you learn the basics.

If you prefer a GUI, you can use GitHub Desktop on both macOS and Windows. Read the user guides for more instructions.

General permissions

If you haven't already, signup for a GitHub account. Send your GitHub username to one of the TritonDataCenter owners to be added to the GitHub organisation. This will allow you to see TritonDataCenter's public and private repos.

If you're unsure of who to ask for permissions, ask your manager.

Contributing directly to a TritonDataCenter repository

In order to contribute directly to a repository, you must get permission from a TritonDataCenter owner. You can contribute PRs to any repository by creating a fork.

Creating your fork

Once you’re in the TritonDataCenter GitHub organisation, go to the repo which you wish to contribute to. In the top right corner, click Fork to add a copy of the repository to your account.

Forking a repository means that you can make changes without directly affecting the original repository.

Cloning a local copy of your fork

To create a local version of your forked repository, you must clone it to your local environment. This clone is where you'll do all of your work.

You can clone it with the help of GitHub desktop or via the commandline:

1. Create a directory for your repository and get into the directory.

   $ mkdir local-fork
   $ cd local-fork

2. Clone the repo from your fork.

   $ git clone github.com/<your-username>/<repo-name> .

   NOTE: The . at the end clones the repository into your directory instead of creating a new directory.

3. Set up the upstream remote. This is what git calls the repo that your forked from.

   $ git remote add upstream github.com/joyent/documentation

Setting up the upstream remote will ensure you can sync the latest updates from the original repository.

Basic workflow with the commandline

1. Go to your local repository copy.

   $ cd path/to/your/fork

2. Sync your master branch with the main (upstream) repo to make sure that you have the latest version of everything.

   $ git checkout master
   $ git fetch upstream
   $ git merge upstream/master

3. Create a branch for your work. The branch name should be something meaningful. The name is temporary, but it is helpful for sorting through a large number of branches.

   $ git checkout -b update-getting-started-docs

   NOTE: When creating a branch related to a JIRA ticket, prepend the branch with the ticket name (i.e. DOC-756-, SWSUP-1030-). When creating a branch related to a GitHub issue, prepend with the issue number (i.e. 32-, 183-).

4. Work on the files that need work.

5. Add and commit those changes.

   $ git add filea.md
   $ git commit

6. Push your branch changes to your GitHub repo.

   $ git push origin addhowtos

Make a Pull Request

When you've pushed the last changes to your working branch, and you want your work merged into the main repository, issue a pull request.

1. Log in to your GitHub account.
2. Go to your fork of the repository.
3. Make sure your work branch is selected.
4. Click Make Pull Request.

When your pull request gets merged into the main repo, you will get a notification.

You will notice that your working branch has been deleted. This is perfectly normal.

Then resume with the basic workflow, syncing up with the main repo before starting to do new work.