Maintainers Guide

This page describes how to do various code maintenance related tasks for GRASP.

• Checking out a pull request
• Creating releases

Checking out a pull request

This describes the procedure to get the version of the code proposed in a pull request onto your own computer so that you could compile and test it.

You need to know the submitter's GitHub username and what they called their branch. You can get that information directly from the header of the pull request on GitHub:

The part underlined in red is the user name (USERNAME below) and the part underlined in blue is the branch name (BRANCHNAME below).

To actually then download their version of the code to your computer, you need to run the following commands (replacing USERNAME and BRANCHNAME as needed):

# Clone the CompAS repository, if you already haven't
git clone https://github.com/USERNAME/grasp2018.git
# do this instead if you have SSH keys set up:
#git clone git@github.com:compas/grasp2018.git

# cd into your local repository
cd grasp2018

# Add the fork as a separate Git remote
git remote add USERNAME https://github.com/USERNAME/grasp2018.git
# do this instead if you have SSH keys set up:
#git remote add USERNAME git@github.com:USERNAME/grasp2018.git

# Fetch the contents of the forked repository
git fetch USERNAME

# Checkout the PR branch
git checkout BRANCHNAME

# After this your worktree (i.e. the files on the disk) should correspond
# to the code in the pull request. Check this by running
git status
git log
# git status should say "On branch cff/fix-error1" and the log should show
# the relevant commits.

Creating releases

This describes the step by step procedure to create a tarball of GRASP based on a version in the Git repository, for submission to CPC for example.

I am assuming the the main development branch is master and it has been updated in the CompAS repository with all the planned changes.

1. A new release should be created from the master branch.

   Release naming. The current practice is to use the date of the release in the ISO 8601 format as the name (i.e. YYYY-MM-DD). E.g. the original CPC submission had the name 2018-09-10.

   To make a release, first go to the "Releases" page of the CompAS GRASP repository and click the "Draft a new release" button:

   

   This will take you to the new release page:

   

   Here you should fill out the tag name and some other information:

   • Tag version -- the name of the tag (i.e. YYYY-MM-DD, with the current date).
   • Target -- the branch that the release will be created off. Should normally be master.
   • Release title -- optional, but should probably minimally be the name of the tag.
   • Release notes -- optional, but should describe the release.

   Once the form is filled out, you should click the green "Publish release" button to create the corresponding tag and publish the release to the world.

   You can also save it as a draft, e.g. to have someone else double check the release before publishing it.

2. You should now update git fetch the CompAS repository to your local machine to fetch the new tag.

   NB! If you are working with forks, you probably have cloned your fork, instead of the CompAS repository (i.e. the origin remote points to your fork on GitHub, and not to the CompAS repository; you can check this by running git remote -v). In this case you need to set up another remote to the CompAS repository:

   git remote add compas git@github.com:compas/grasp2018.git
   

   This creates a new remote called compas that points to the upstream repository.

   You can now update your local repository with the CompAS updates by running

   git fetch compas
   

3. Create an archive of the files. In the grasp2018 repository root directory run:

   git archive --prefix=grasp-YYYY-MM-DD/ -o ../grasp-YYYY-MM-DD.tar.gz YYYY-MM-DD
   

   • The --prefix option puts all the files into a subdirectory called grasp-XXXX-XX-XX/. NB! Make sure you have a slash at the end, because otherwise it will just prepend the string to the filenames.

   • The -o option specifies the name of the output archive file.

   • The last argument to git archive specifies the tag or branch you want to create an archive of.

You will end up with a compressed tarball called grasp-YYYY-MM-DD.tar.gz in the parent directory of the grasp2018 repository, which contains all the source files in the repository, matching byte-by-byte with the version controlled ones.

To make sure there was not a mistake with e.g. the tag names etc., it is recommended that you unpack a file or two from the tarball and check that they indeed contain the latest changes.