CONTRIBUTING.md

Contributing to cmsgemos

The following are a set of guidelines to help you in contributing to the cmsgemos code base.

How to start developing

Start by forking the central cmsgemos repository. Once you have your fork, then you can check it out to wherever you will be developing.

Workflow

We have been utilizing a very helpful guideline for our development model outlined here: git-flow The basic idea is the following:

• fork from cms-gem-daq-project/cmsgemos

• create a branch to develop your particular feature (based off of develop, or in some cases, the current release branch)

  • hotfix- may be created from master
  • bugfix- may also be created from a given feature branch
  • once that feature is completed, create a pull request

• master should always be stable

  • Do not commit directly onto master or develop, and ensure that your master and develop are always up-to-date with cms-gem-daq-project before starting new developments

• Some generally good guidelines (though this post recommends not using the git-flow model)

  • Never use git commit -a
  • Avoid git commit -m over git commit -p or git commit, as it will force you to think about your commit message
    • Speaking of... commit messages should be descriptive, not like a novel, but concise and complete. If they reference an issue or PR, please include that information.
  • Prefer git rebase over git pull (or configure git pull to do a rebase)
    • You can set this up either in the repo .git/config file per repo, or per branch, or globally via ~/.gitconfig
    • Golden rebase rules
      • Executive summary: never rebase a public branch, i.e., a branch you have pushed somewhere, and especially not a branch that others may be collaborating with

Coding Style

• Avoid using tabs, use an editor that is smart enough to convert all tabs to spaces
• Current convention is 4 spaces per tab for python and c++ code

Testing

• You should, at a minimum, test that your code compiles, and if possible, test that it runs without crashing
• When testing the python package, you should set up a virtualenv and use pip to install the zip created by:

cd gempython
make cleanrpm
make rpm

• If you also need to test this against other gempython packages (gemplotting, vfatqc), you should find the release that is compatible from the releases page of the repository and use pip to install them into your virtualenv

Environment

To be filled in

Making a pull request

Once you have tested your code, you are ready to make a pull request. If it references an issue or another pull request, make sure to include that information.

Continuous Integration

We have set up travis-ci to perform some basic CI/CD tasks for github pushes, and gitlab-ci for the gitlab mirror. The workflow is based on Docker images that have been set up to be similar to the 904 lab machines

Using Labels

Issue and Pull Request Labels

There are several labels used to track issues. Unfortunately, due to the way that github is set up, general users are not able to add these labels. As such, they are outlined here, and when creating an issue or pull request, should be referenced in the title so that the maintainers (or a friendly bot) can apply the appropriate label easily.

Label name	cms-gem-daq-project/cmsgemos 🔎	cms-gem-daq-project 🔎	Description
Type: Bug	search cmsgemos for issues	search cms-gem-daq-project for issues	Issue reports a bug, and supplementary information, i.e., how to reproduce, useful debugging info, etc.
Type: Bugfix	search cmsgemos for issues	search cms-gem-daq-project for issues	Issue reports a bugfix, and references the bug issue
Type: Duplicate	search cmsgemos for issues	search cms-gem-daq-project for issues	Issue will be tagged as duplicate, and a reference to the initial issue will be added
Type: Enhancement	search cmsgemos for issues	search cms-gem-daq-project for issues	Issue reports an enhancement
Type: Feature Request	search cmsgemos for issues	search cms-gem-daq-project for issues	Issue contains a feature-request
Type: Maintenance	search cmsgemos for issues	search cms-gem-daq-project for issues	Issue reports a maintenance or maintenance request
Type: New Tag	search cmsgemos for issues	search cms-gem-daq-project for issues	Issue reports a bug, and supplementary information, i.e., how to reproduce, useful debugging info, etc.
Type: Question	search cmsgemos for issues	search cms-gem-daq-project for issues	Issue raises a question, though it will generally be better to contact on mattermost
Type: Answer	search cmsgemos for issues	search cms-gem-daq-project for issues	Issue will answer a previously referenced question

Issue and Pull Request Labels

Maintainers (or a friendly bot) will (hopefully) attach a priority based on the information given in the issue/PR.

Label name	cms-gem-daq-project/cmsgemos 🔎	cms-gem-daq-project 🔎	Description
Priority: Low	search cmsgemos for issues	search cms-gem-daq-project for issues	Priority low assigned to issue/PR
Priority: Medium	search cmsgemos for issues	search cms-gem-daq-project for issues	Priority medium assigned to issue/PR
Priority: High	search cmsgemos for issues	search cms-gem-daq-project for issues	Priority high assigned to issue/PR
Priority: Critical	search cmsgemos for issues	search cms-gem-daq-project for issues	Priority critical assigned to issue/PR

Pull Request Status Labels

Maintainers (or a friendly bot) will (hopefully) properly migrate issues and pull requests through the various stages on their path to resolution.

Label name	cms-gem-daq-project/cmsgemos 🔎	cms-gem-daq-project 🔎	Description
Status: Blocked	search cmsgemos for issues	search cms-gem-daq-project for issues	Issue/PR blocked: depends on some other issue/PR (should be referenced)
Status: Pending	search cmsgemos for issues	search cms-gem-daq-project for issues	Issue/PR pending: acknowledged, ready to be reviewed
Status: Accepted	search cmsgemos for issues	search cms-gem-daq-project for issues	Issue/PR accepted: accepted
Status: Completed	search cmsgemos for issues	search cms-gem-daq-project for issues	Issue/PR completed: ready for inclusion
Status: Invalid	search cmsgemos for issues	search cms-gem-daq-project for issues	Issue/PR invalid: invalid, possibly can't reproduce
Status: Wontfix	search cmsgemos for issues	search cms-gem-daq-project for issues	Issue/PR wontfix: won't be included as-is
Status: Wrong Repo	search cmsgemos for issues	search cms-gem-daq-project for issues	Issue/PR wrong-repo: issue reported in incorrect repository
Status: Help Wanted	search cmsgemos for issues	search cms-gem-daq-project for issues	Issue/PR help-wanted: call for someone to take on the task
Status: Revision Needed	search cmsgemos for issues	search cms-gem-daq-project for issues	Issue/PR revision-needed: something needs to be changed before proceeding
Status: On Hold	search cmsgemos for issues	search cms-gem-daq-project for issues	Issue/PR on-hold: being worked on, but either stale, or waiting for inputs
Status: In Progress	search cmsgemos for issues	search cms-gem-daq-project for issues	Issue/PR in-progress: actively being worked on
Status: Review Needed	search cmsgemos for issues	search cms-gem-daq-project for issues	Issue/PR review-needed: ready for inclusion, needs review

Acknowledgements

• Much style and syntax of this was borrowed heavily from the atom repository