Tutorial - Releasing package version
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:
- 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.
- merges the package’s
integration
branch in themaster
branch. If merge is conflicting then the release stops here and package is put in its original state. - tags the last commit on
master
with adequate version tag. - build again the package on
master
branch (with options limited to the strict minimum) to ensure that enerything is ok. - 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. - goes back to
integration
branch and increments the version number in the rootCMakeLists.txt
. The new version number simply increases the previous minor number by default, but this can be controlled by themake release
command (usingnextversion
argument). - updates the
integration
branch of local andorigin
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.