Guide for working with git and github for Variant

01-routines.md

Routines for working with content on Github for Variant

We are open. This means we should work in an open way. Run like an open source project. Any significant amount of work* should be done through Pull Requests. Pull Requests are suggestions for a project which projects can accept and update their own content. This is a great way to frame discussions.

(* Significant amount of work in both scope and impact. Things like infrastructure, bug fixing, minor details can be committed directly to master without doing a Pull Request.

Reviewing

Pull Requests should be reviewed equally, no matter who created the pull request. Communication should be polite, friendly and welcoming. Even though the change isn't what we want, we should appreciate the work put into it and the effort.

When we get a Pull Request, two people should review it. If both people are happy, we can accept the changes (merge). If you see a Pull Request without reviewers: Set yourself as a reviewer and add one or more additional reviewers. If the content is of a change that is relevant to other people, add them as reviewers also.

Try to review as quickly as you are able and get the changes in. We do not want long running Pull Requests. That is demotivating for the people sending the pull requests and it is more work.

Creating a Pull Request

Try to include the following information:

1. What is this change
2. Why is this proposed
3. If applicable: Include screenshots of the change. Not relevant on text changes only. See example

If you can, try adding the reviewers you think are relevant for this change.

02-pull-request-dev.md

Guide for sending pull request from local dev environment

See prerequisite appendix: 08-setup-dev.md

There are two ways of doing this: Either you have push access directly to the repo, or you don't. If you do see With push access. If you don't see Without push access.

With push access

# Example Handbook
git clone https://github.com/varianter/handbook.git

Changes should be done on a different branch than master:

git checkout -b myBranch

This creates a new branch and navigates to that branch. Here you can make your changes and commit them. You can also push to the repository directly on that branch. After pushing you will see a button called Create Pull Request when visiting the repository on Github. Click this and follow step Creating a Pull Request in the routines section.

Without push access

If you don't have directly access to the repository you need to fork it first. Forking is creating your own copy of the repository on your account. When doing this you can follow the same process as above, but instead of cloning and pushing to the varianter user, you use your own username:

# Example Handbook
git clone https://github.com/<USERNAME>/handbook.git

02-pull-request-github.md

Guide for sending Pull Request through Github

See https://help.github.com/articles/editing-files-in-your-repository/. More info to come.

Important: Make sure to mark the Create a new branch options when proposing file changes.

08-setup-dev.md

Setting up git locally

This is a prerequisite for working with git locally in "dev mode"

Setup git and set proper settings:

From https://help.github.com/articles/set-up-git/:

Run following commands:

git config --global user.name "My Full Name"
git config --global user.email "my@email.com"

(Note: The email you add should be the same as the one you used to register at Github as that is used to match with your profile)

Setting two-factor

You should be using two-factor authentication. See guide: https://help.github.com/articles/configuring-two-factor-authentication/

Cloning a repo

When cloning a repo it is recommended by Github to use HTTPS instead of SSH. HTTPS is accessible from most places and you don't have to worry about ports being open. When using HTTPS you provide username and password.

Important: If you have activated two-factor auth (you should), you don't provide your personal password, but you generate an access token instead. See https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line

You don't have to remember your access token. You can use cache your password with git. On macOS you can use the built in keychain to do this. Activate by

git config --global credential.helper osxkeychain

(If you are using another OS or if this doesn't work you might have to install keychain helper. See https://help.github.com/articles/caching-your-github-password-in-git/)