Step 5 : Saving current development state

You can continue working on your package, by adding source files, creating new libraries and applications, etc.

From time to time (at least each day), it is a good practice to save the current revision of your package. To do so, simply use git:

cd <my-first-package>
git add -A
git commit -m "modifications your perfom from previous state"

At this time the new commit should have been added to the integration branch of your package’s local repository. Then when you want to save your work in a online server simply do:

cd <my-first-package>
git push origin integration

You should always push to the integration branch (or eventually another specific branch) but never to the master branch until you want to release a new version. We advise you to have a look at git tutorial here to better use git than the really raw (but simple) way of doing presented in this section.

Also, when working with manual git commands, you should always push integration branch to the origin remote.

Another option, to avoid mistakes in git usage, is to use PID dedicated command:

cd <my-first-package>
pid integrate

This command will also manage the update of your integration branch from information coming from the origin remote before pushing your own commits.

Step 6 : Releasing a package

From time to time, you will have to release your package when you think its state is stable enough. When released it is supposed to be usable by a third party that has access to it. In the end a release is not more than an interesting state of the project, corresponding to a specific git commit. As usually done in modern development process, a release of a package is bound to a specific version number.

6.1 Apply a software license to source files

Before releasing it is most of time a good thing to apply the chosen software license (see root CMakeLists.txt file) to your source files so that the corresponding copyrights applies to all parts of your package without possible legal bypassing. To do so:

cd <my-first-package>
pid licensing

The operation may take a long time (depending on how many files rely in your package). To see the result open any source file and look at its header: it now contains license information.

Then remember to save the modifications:

cd <my-first-package>
git add -A
git commit -m "explanation of modifications your perfom from previous state"

6.2 Generate API documentation

As it is supposed to be accessed by other person, it is also a good thing to provide an API documentation for this package.

cd <my-first-package>/build
ccmake ..

In the CMake configuration interface, set BUILD_API_DOC to ON, then type c then g.

Then:

make build

Otherwise simply use the pid script to do this all in one:

cd <my-first-package>
pid build -DBUILD_API_DOC=ON

The build process will inform you from missing information in the API (e.g. missing parameters of a function and so on). It is a good pratice to try to resolve these errors by modifying or adding adequate doxygen comment directly into the header files of your library (only headers are taken into account for API documentation). You can find the resulting API in <pid-workspace>/install/<platform>/my-first-package/0.1.0/share/doc/html. Simply open the index.html file with a web crawler and see the result.

Once you think that the result is satisfying, remember to save the modifications:

cd <my-first-package>
git add -A
git commit -m "explanation of modifications your perfom from previous state"

6.3 Release the current version

After these cosmetic (but usefull, in the end) operations you can release the current package version. This operation simply consists in marking a specific state of your package’s repository. This is performed, among other operations, by tagging this specific state by using git tags. The main goal of a release is to be able to quickly find a functionnal version of your code. The best way to perform this operation adequately is to use PID dedicated commands:

cd <pid-worskspace>
pid release package=my-first-package

The release process automatically performs following actions:

  1. tries a first build with all tests activated (if any), to check if code can be compiled and tests pass. If not successfull the release process stops here.
  2. merges the package’s integration branch in the master branch. If merge is conflicting then the release stops here and package is put in its original state.
  3. tags the last commit on master with adequate version tag.
  4. build again the package on master branch (with options limited to the strict minimum) to ensure that enerything is ok.
  5. updates (i.e. push to) the official remote repository of the package (master branch and tags). This may launch the CI process of the package on server side.
  6. goes back to integration branch and increments the version number in the root CMakeLists.txt. The new version number simply increases the previous minor number by default, but this can be controlled by the make release command (using nextversion argument).
  7. updates the integration branch of local and origin repositories.

After that, you are still on integration branch but any further build will install a new version (e.g. 0.2.0).

Now you know how to release a package, let’s see why you need to register it.