Getting started with Github and Git for development of CIF dictionaries

Getting started with Github and Git for development of CIF dictionaries

The following is a convenient workflow. See here for Git downloads and free book.

First-time setup

1. Signup to Github
2. Fork the repository you want to work on to your own Github area (see "Fork" button at top right of the repository web page)

Web-based workflow

Github makes it possible to do everything through the browser, but it becomes a bit tedious for large changes. See below for a workflow involving your local computer.

Routine workflow

The following instructions assume you have the "<> Code" tab open in your own fork of the repository in Github.

2. Bring your local "main" branch (may be called "master" or "main") up-to-date: make sure the "master" or "main" branch is selected in the grey button above the code listing, then click "Fetch upstream"
3. Create and checkout a new "topic" branch for the particular changes you want to make: click the "master" branch button and fill in the name of the new branch.
4. Make and save all the changes you want using the Github editing interface
5. Create a pull request. Github will normally provide a big banner at the top of the "Code" page of your Github fork suggesting this when you navigate back to the "<> Code" tab and select your custom branch. Explain what your changes do in the pull request comment box that is provided
6. After this pull request is created, somebody will look at it, comment on it, and either merge it or wait for further comments/changes from you. To update your work in response to comments, simply repeat step 5 making sure your custom branch is selected. The pull request will be automatically updated and all commenters notified every time you save something in step 5. Also, each time a pull request is created/updated, automatic checks are run on the pull request to check syntax and DDL dictionary conformance (if they have been set up).
7. The pull request is merged. As a matter of good practice, someone other than the submitter should merge the pull request, unless there are no other collaborators on the dictionary.

Workflow using local computer

Although a few extra steps are involved, the benefit of using your own computer is that your favourite editing tools and text tools are available, and you have more control over when you commit a chunk of changes.

0. Install git tools on your own computer. See here for downloads and free book.
1. In Github, fork the repository you want to work on to your own area (see "Fork" button at top right)
2. On your own computer, clone a copy from your repository (see the green "Code" button on the Github "<> code" tab for instructions)

Routine workflow

3. On your computer, change to your local "main" branch (may be called "master" or "main") and make it up-to-date: git checkout master; git pull
4. On your computer, create and checkout a new "topic" branch for the particular changes you want to make: git switch -c <branchname>
5. Make all the changes you want on your computer
6. Record all changes to your local copy: git commit -a. Do this multiple times to accumulate changes in digestible chunks.
7. Transfer the changes to your github copy: git push origin <branchname>
8. On Github, create a pull request. Github will normally provide a big banner at the top of the "Code" page of your Github fork after you have done step 7 asking if you want to do this. Explain what your changes do in the pull request comment box that is provided
9. After this pull request is created, somebody will look at it, comment on it, and either merge it or wait for further comments/changes from you. Repeat steps 4-9 each time you respond to these comments, skipping 8 as the pull request will be automatically updated and all commenters notified every time you do step 7. Each time a pull request is created/updated, any automatic checks are run on the pull request to check syntax and DDL dictionary conformance.
10. The pull request is merged, preferably by someone other than the committer.

Hygiene

Beware of accidentally starting a new set of changes from an old topic branch or out-of-date local master branch. While it is easy to recover after doing this, it can be annoying, so don't skip the first step of "Routine workflow" above. You may also consider deleting the branch both in Github and locally using git branch -d <branchname> after the pull request has been merged. Fun fact: all of the changes contained in the branch are still present in the git repository after deletion.

Working on several different projects at once

If you don't want to wait for one pull request to be accepted before starting on another project, that won't cause extra work if they affect different areas of the same file or different files.

1. Create a separate topic branch based on current master: repeat first step of "Routine workflow" above
2. Make and commit your changes and create a pull request as above
3. If your changes and any other changes from other pull requests do not overlap, they will merge as usual
4. If not, the conflicting changes should be manually merged into one or other of the pull request branches by merging from the relevant branch of the other pull request - best done on your local computer.