contributing workflow

Contributing code

Here are some things to keep in mind when contributing code to ASGarD. Following the advice here will result in a much better experience for both you and the maintainers.

1. We guarantee a PR review turnaround time according to the following formula:

    max # business days review turnaround = 2^(# lines in PR / 100)
   

2. Please feel free to open an issue or even a PR with the label [WIP] to discuss your idea. Early feedback is your friend.

3. Familiarize yourself with our expectations for contributed code.

4. If you like, take a look at the code review checklist that we try to follow.

Workflow process

We use the gitflow model of development, but without forked repositories. This allows new code to undergo review and testing in an effort to increase quality and maintainability, a better release process.

This simplified gitflow is also described as gitlab flow, where ASGarD also uses release branches.

This section will first describe how to set up a git environment to use github for asgard development, and then how to use that environment to develop new features and contribute them back to the asgard project.

Once your git-asgard development environment is set up, day-to-day development can commence. This is a cyclic process that starts with creating a new branch for a feature, and ends when that feature branch gets merged into the public asgard repository via a pull request.

Workflow summary

Note: Just reading this summary won't be enough the first time. Read the whole document!.

1. Open an Issue with the code label before starting work. Describe the proposed changes.
2. Create a new branch from 'develop' for your bugfix, feature, or enhancement, and checkout this new branch: git checkout -b <uid>/<feature_branch>
3. Commit your changes: git commit (be sure your environment is correctly configured for committing: see below.)
4. Push the changes in your branch to asgard/asgard : git push -u origin <feature_branch>.
5. Submit your change to asgard/asgard by opening a pull request. After submitting the PR, the code is reviewed by the reviewers/maintainers according to the Code review checklist Once the reviewers and PR author reach an agreement, the author asks a maintainer to merge the changes.
6. After the PR is merged, delete the local branch git branch -d <feature_branch> if desired. It will automatically be deleted in the upstream repository.

Setup your environment

The steps in this section should be a one-time process. The first step in the recurrent day-to-day development of ASGarD using git starts with the "Create a separate branch" step below.

Basic git settings

Git attaches a name and email address to each commit in the logs, and this email address is also used to associate commits with the contributing github account. Be sure that the email address you use here is one associated with your github account (add email addresses under account settings), as this is used to link github users to git commit authors. Use the following commands on any machine where you will be using git for ASGarD development (replacing your name and email as appropriate):

$ git config --global user.name "Firstname Lastname"
$ git config --global user.email "[email protected]"

Using --global is optional and places the supplied information into ~/.gitconfig where more useful configuration can be added. Here is a simple ~/.gitconfig. Git has many useful optional settings, see $ git --help config for more details.

For more useful git configuration hints, see this wiki's page on git shortcuts and configuration

Clone your copy of the ASGarD repo

Cloning your ASGarD copy will download the code to your local machine so that you can make edits. This downloads the entire repository.

$ git clone https://github.com/project-asgard/asgard.git

caching git username/password

To avoid typing your username for remote git operations, you can modify the above command to add your github user ID before the URL:

$ git clone https://[email protected]/project-asgard/asgard.git

Also, refer to this page for some strategies for not having to type your password for remote git operations.

At this point, your git-asgard development environment should be set up and ready for day-to-day development activities.

Create a separate branch

All development in ASGarD should take place in "topic branches" or "feature branches." These are created from the long-lived develop branch, and once completed, they will be merged back into develop via a pull request. Branch names should start with your userid, and then be a brief description of the branch's purpose, and could include an issue or bug number.

If it has been a while since you cloned the local repository, you may want to be sure your local develop branch is up to date with asgard/asgard's develop:

1. Pull new changes from the upstream repository into your local repository.

    $ git checkout develop
    $ git pull
   

2. To create a new branch from develop:

    $ git checkout develop
    $ git checkout -b <uid>/<feature_branch>
   

To see all of the branches in your local repository with some useful information about them, use

$ git branch -avv

Code modification and testing

To run the unit tests, execute the asgard-tests binary and ensure that it reports all tests have passed.

(TODO: add additional information about how/why/when to run the different types of ASGarD tests)

Commit the changes

During development, there are a few git tools/commands that can be used to help manage and organize code commits.

$ git status	check which files have been changed
$ git add new_file.cpp	add new and changed files to the index to be committed
$ git diff	see changes in the working directory vs. the previous commit
$ git diff --staged	see changes in the index vs. the previous commit
$ git commit	locally commit the changes staged in the index
$ git commit -a	commit all changed/deleted files (automatic staging)
$ git add -i	interactively stage parts of changed files

Commit messages

A git commit message has two parts: a summary (the first line) and the description.

Formatting the commit message

• There should be a single line summary of 71 characters or less which allows the one-line form of the git log utility to display the summary without wrapping.
• A blank line separates the summary and the body.
• All lines of the body should be a maximum of 78 characters to display correctly in all terminal types and online tools.

There are several things that make a truly excellent commit message. Projects that consistently make an effort at good commit messages are much more pleasant to work with than those whose histories have "bug fix," "typo," and "new feature" throughout.

• The first line summary should give a brief description of what the commit does. git log --oneline and many parts of github only show the first line of the commit, so it is important that the summary be as useful as possible.
• The summary can be given a larger context using a colon by convention. For example, "inverse update: added cublas capability to Fahy algorithm" This isn't mandatory since one can get the files changed by a commit, but it adds convenience when scanning through the logs and is a good practice.
• The description should be written in plain English and give details as to what the commit does, known issues, and an example if possible.

Tidying commits

([MGL] squash typos/bugfixes out of intermediate commits)

Create a pull request

After you are confident that your branch passes all tests and follows the Coding conventions in ASGarD, you are ready to submit a pull request.

1. Push your branch that has the new feature to the main asgard repository on github:

    $ git push -u origin <feature_branch>
   

2. Create the pull request using the github web interface. Once you have pushed your branch to github, several buttons will show up that allow you to start a pull request. They all eventually accomplish the same thing.

   On the next screen, there may not be any changes shown. Be sure to specify the correct source and destination branches for the pull request using the drop down menus.

Pull request title and description

Just like commit messages, the pull request title and description should provide good documentation and historical reference.

See also GitHub's "How to write the perfect pull request" page.

• The title should be brief and descriptive.
  • Do not reference issues or bug numbers in the title. These go in the description.
  • Prefix the title with "[WIP]" if you don't want the PR merged yet, but do want some discussion or code review for your work. You can close the PR to keep working, or remove the "[WIP]" prefix when it is ready to be considered for merge.
• The description describes what you have done.
  • Include references to issues and bugs with "#1234", and github will automatically create the link for you. This syntax also works in the PR discussion.
  • If you include auto-close syntax in the description, the corresponding github issue in the same repository will be automatically closed when the PR is merged. This syntax doesn't work in the pull request discussion.
  • In the PR description or later discussion, you can @mention users or teams that you want to be aware.

It is also recommended that you request the appropriate reviewer(s) that will have some prior expertise about the changes being added by the pull request.

Updating pull requests

It is very common to need to make changes to the code after the pull request has been submitted, e.g. as a result of code-review and discussion. To update the pull request with new code, simply make the changes in the same branch, commit, and push the new commits to github.

$ git commit
$ git push

Note that if you edit your commit history of the branch under PR in any way, you will need to force push.

$ git push -f

Synchronizing with develop asgard/asgard

Once in a while, you will need to sync your branch with 'develop' from the original asgard/asgard repository. This can happen when:

• Someone tells you that there are merge conflicts
• github/CI/Jenkins tells you that your branch could not be automatically merged
• You need some new change from 'develop' that was made/merged after you started your branch.

Note that you shouldn't make a habit of merging 'develop' into your feature branch every time there is an update - only if you think it is necessary. Hopefully your feature branches don't last very long anyway, so this issue is mitigated.

If you do need to update your feature branch for one of the reasons listed above, you simply need to merge 'develop' from upstream (asgard/asgard).

1. Pull new changes from the upstream 'develop' into your local feature branch.

    $ git checkout <feature_branch>
    $ git pull upstream develop
   

Delete the branch

Once the branch has been merged into the 'develop' branch asgard/asgard from the pull request, you may now delete the branch from your local and/or forked github repositories. The branch in your github fork will normally be deleted for you as part of the merge, but you will still need to delete it from your local repository clones.

To delete a branch in your local repository:

$ git branch -d <feature_branch>

To delete the branch from your remote github fork, you push a null branch (usually not necessary):

$ git push origin :<feature_branch>

FAQ/Troubleshooting

1. How can I avoid typing my username and password all the time?

   • for usernames, include it in the repository url when cloning, adding a remote, etc. E.g. git clone https://[email protected]/username/asgard.git and git remote add upstream https://[email protected]/project-asgard/asgard.git
   • for passwords, there are a couple of options:
     1. Use SSH keys
     2. Cache your password for a certain amount of time. Add the following to your ~/.gitconfig: [credential] helper = cache --timeout=3600
     3. Use gpg as described in the git credentials wiki page.

2. git diff and git log don't show colored output (e.g. on Titan)

   be sure to have the following in your ~/.gitconfig file:

    [color]
      ui = auto
   

   and set your $PAGER environment variable to "less -R"

3. Titan has a very old version of git installed that doesn't support, e.g., git branch -u

   Some LCF machines have very old git versions as part of the OS that don't support the git branch -u option. Titan and Mira have newer git versions built and available as a module. It is recommended to always use a more recent version of git to avoid unexpected changed/deprecated behaviors.

   Alternatively, for git versions at or before 1.7.12, the git branch --set-upstream branch_name your_new_remote/branch_name is equivalent to the -u variant given above.

4. Is there additional material on the web that can be used for learning git?

   • The entire Pro Git book is available online for free.

   • There are several pages https://grahamlopez.org/git with intermediate material.

   • www.lynda.com has a 6-hour online training course that is self-paced on your own schedule. The name of the course is "Git Essential Training" -- it is very good and goes into a lot of detail. The one topic it does not cover is pull requests, otherwise it explains a lot of the basics including that "philosphy" of git which is very different from svn. Lynda.com can be accessed via a LinkedIn account. This service is normally available by a monthly paid subscription, but they have a no-cost 30-day free trial that can be used for accessing this course.

References

This page takes content from GitHub and Gitlab help pages, and is heavily inspired by the Sympy development guide.