General branching model in PID

For each type of deployment unit in PID, we propose to follow a common branching model:

Permanent branches

Each deployment unit has 2 permanent branches :

  • master that reflect last stable state of the deployment unit
  • integration that contains current development state of the deployment unit. It is use to merge features coming from developpers (direct merging) or from external contributors (using merge requests).

For native packages, integration branch is mandatory and always existing as it is used to manage the package release process in a clean way. The integration branch is merged in master, then a version tag is created and then development process can continue on integration. This is among other things the operation performed by the release command:

cd <pid-workspace>
pid release package=target-package

For other deployment units, there is no release process, integration branch is just a facility to separate “work in progress” from “last stable version”.

Note: This same pattern is used for the official pid-workspace project. Anytime someone want to propose modifications to this project (e.g. typically new APIs) they have to propose a merge request on integration branch.

Features branching

The development of new features or patches can be done directly on integration branch or if many developpers work on same package it is preferrable to create dedicated temporary feature branches and merge them on integration when feature is working.

Note: when developping feature branches it is recommanded to use rebasing from time to time in order to keep the history of integration branch as linear as possible. Simply do:

#on a specific feature branch
git rebase integration

If rebasing fails you will have either to:

  • abort rebasing, the history will no longer be linear
git rebase --abort
  • continue rebasing, after solving the problems (which is not always straithforward), this will keep the history linear
#after solving problems
git rebase --continue

Hotfix branching

This branching process should be used anytime you want to solve a bug in an old version of a native package. Indeed native package history management in PID naturally increases the version number for each new release. This is most of time exactly what the user want but sometimes we need to provide a patch for an old version because this version is used as a dependency by many packages. We so need a way to go back in history of versions.

Basic process is sown in previous figure:

  • go back to the version where a BUG has been detected, let’s say 1.1.0, and create
git checkout v1.1.0
  • create a temporary branch for writing the patch. Try to call the branch with a name containing the patch version number to release, something like hotfix-1.1.1 or patch-1.1.1.
git checkout -b hotfix-1.1.1
  • when code is ready, create a release of the patch version:
cd <pid-workspace>
pid release package=target-package branch=hotfix-1.1.1

Usage of git remotes in PID

PID follows the classical git development process for any kind of repository, as described in the following figure:

  • Developpers of a git repository can directly push/pull from it. We call this repository the official repository.
  • Other contributors must before fork the repository inside the git hosting service they use to be able to push/pull content to this one. We cann the fork the private repository.

An important relationship is the pull relationship between official repository and personnal repositories on users’ workstations. Indeed, as explained in the proposed branching model it is important to be able to get updates coming from the official repository since this later contains releases of a package and more generally up to date content.

It is also important to ensure that only developpers of an official repository have the adequaet rights to propose releases of the package. This is simply achieved by the fact theyr are the only one to have push rights on the official repository.

To implement this pattern in the correct way, PID uses 2 different remotes either for deployments units or for the pid-workspace project:

  • official remote targets the official repository at any time.
  • origin remote targets either the official repository or a private repository.

By default, if the user clone a deployment unit (typically a package) from its official repository, or if it uses the deploy command of PID, both official and origin remotes target the same official repository.

Then if the user want to propose modifications it need to change its origin remote to make it target its private repository. This is achieved for instance with the connect command of PID:

cd <pid-workspace>
pid connect package=target-package origin=<address of the private repository>

Whatever the origin remote is, the official remote stays aligned with addresses specified in the deployment unit description (in its root CMakeLists.txt).

As you may have seen there are two types of addresses that you can specify:

  • ADDRESS: this is the default address that is used by package developpers that should be defined anytime a package is suppose to be usable by someone else than just its creator. From a technical perspective this adress wil set the push and fetch adresses of the official remote. This way developpers can always get and publish content from this package. We recommand to use a ssh address to avoid having to enter your password anytime you want to push.
  • PUBLIC_ADDRESS: this is an optional, but often used, address to allow third party to get the content of the deployment unit. This address should be the http or https address of the official repository and the repository should be publicly accessible (anyone without access should be able to clone/pull it). From a technical perspective this adress force the fetch adress of the official remote to use this public address.

PID uses all those information to allow third party to propose modifications to official repositories while preserving the capability of anyone to deploy or update deployment units content from their official repository.

About migration of the official repository

Sometimes there may have a migration of the official repository of a given deployment unit.

Here is the typical migration process:

  • move the project in current git hosting service, or push the project into another hosting service (and eventually mirror this new repository in original hosting service if you want to keep it available in this service). You now have a new official repository.

  • in your deployment unit description, change the ADDRESS and PUBLIC_ADDRESS to their new value. Commit and push to the new official repository.

  • Register again the deploymen tunit:

cd <pid-workspace>
pid register package=target-package

This updates the reference file for the package and update the contribution space. If you have no push rights to the contribution space repository where it is referenced, propose a merge request.

Once done your deployment unit has been migrated, now everytime your package is deployed it will be from the new official repository.

From user perspective, to get the modification they need to update their contribution spaces:

cd <pid-workspace>
pid upgrade #will update everything

Then when they will reconfigure their deployment unit, the official remote will be detected as changed and the process should automatically set its push and fetch addresses to the correct values.

About contribution spaces

Contribution spaces are specific entities and do not behave exactly as deployment units:

  • they do not have and official remote but only an origin remote. They update is so made directly from origin.
  • it is possible to set the fetch and push adresses of their repository. Their UPDATE remote is default and mandatory, it defines the fetch address and also by default the push address. Their PUBLISH remote can be defined to force the push address.

This way same kind of fork/merge request methodolgy can be put in place as for deployment units, the push address allowing to target a private repository from which a merge request to official repository can be proposed.