Package Development

Package Development Procedure

Use Git as Version Control

Git is a distributed version control system.

It is easy to find various tutorials about git from internet. Here are some links which may be helpful:

• git - the simple guide. A very simple guide for getting started with git.
• Git Reference. A quick reference for git.
• Pro Git Book. This book contains every details about git.

Package Development Procedure

Create a New Package

For developing a new package, first create new project on the CEPC GitLab.

Already Existed Project

The project should be cloned for the first time.

git clone git@cepcgit.ihep.ac.cn:cepcsoft/package_name.git

It is a good practice to create and checkout a new branch to do the development:

git checkout -b new_development

After changes are done, it can be merged to master branch:

git checkout master
git merge new_development

If you would like to publish it to GitLab, make sure you are playing with the latest code:

git fetch origin
git merge origin/master

Conflicts may occur when doing the merge. If any conflicts found, please solve that carefully and then commit:

git add <conflict_files>
git commit

Now it is ready to push to GitLab:

git push origin master

You need proper authority to do the push, or you have to create a merge request on GitLab.

Define a Version

A version must be defined when the package is ready for releasing to others.

Version Number Convention

The version number normally consists of three parts: major, minor and patch. e.g., in version “1.2.3”, “1” is the major version, “2” is the minor version and “3” is the patch version. Sometimes the patch version may be omitted for simple cases, e.g., version “1.2”.

Given a version number MAJOR.MINOR.PATCH, increment the:

• MAJOR version when you make incompatible API change,
• MINOR version when you add functionality in a backwards-compatible manner
• PATCH version when you make backwards-compatible bug fixes

Here is something more about versioning.

How to Define a Version

For a normal package with CMake suppport, edit CMakeLists.txt and increment the version numbers:

SET( ${PROJECT_NAME}_VERSION_MAJOR 1 )
SET( ${PROJECT_NAME}_VERSION_MINOR 5 )
SET( ${PROJECT_NAME}_VERSION_PATCH 0 )

If it is not a standard CMake project, find the place to setup version elsewhere, or just skip this step.

Commit and then tag the version:

git commit -a -m 'Ready to release version 1.5.0'
git tag -a v1.5.0 -m 'Version 1.5.0'
git push origin v1.5.0

Remember to prepend the letter “v” before the version name which implies that this tag stands for a version.

Notice

NEVER change a version once it is released. The same version number should always indicate exactly the same contents.

If any bugs are found, a new patch version should be created for the bug fixes.