Developer procedures - soctrace-inria/ocelotl GitHub Wiki

Summary

This page describes some procedures related to Ocelotl maintenance. It follows the Framesoc developpers guideline.

Update Ocelotl website

Ocelotl website is automatically generated by using the GitHub page generators and taking the README.md as input. To update the website the procedure is the following:

  • Update the file README.md, commit and push it on Ocelotl repository.
  • From the Settings page, go to the Automatic page generator.
  • Press the Load README.md button to load the README.md content.
  • Remove the first title, since it is redundant with the web page title.
  • Press Continue to layouts and chose the Slate layout.
  • Press Publish Page.

Note: to change the existing images (or add new images or other kind of resources), you have to add them on the gh-pages branch of Ocelotl repository. This branch contains the actual website content. In the README.md you will have to use the whole url of these resources.

Create a new wiki page

When you add a new page to the Ocelotl wiki, you have to update the wiki sidebar as well. Therefore, the procedure to follow is:

Release Ocelotl

Releasing Ocelotl means uploading a new version of the soctrace-inria update site and creating a new GitHub release. This section describes the procedure to do all of this.

Requirements

Your clones of Ocelotl and soctrace-inria.github.io repositories must be in the same root directory.

For example:

./somedir/ocelotl
./somedir/soctrace-inria.github.io

Update site creation and upload

  • Be sure that ocelotl/fr.inria.soctrace.tools.ocelotl.maven.master/pom.xml is up to date. It must contain all the modules that compose Ocelotl. If it is not the case, add the modules that are missing.

  • Check ocelotl/fr.inria.soctrace.tools.ocelotl.maven.repository/category.xml. It must contain the right metadata and the url to the feature Eclipse plug-in.

  • Go to ocelotl/fr.inria.soctrace.tools.ocelotl.maven.master

  • Change the version using a command similar to the following:

./change_ocelotl_version.sh 1.2.3

Note that the version must have the format x.y.z.

  • If all is OK, commit and push the modifications related to the new version number.

  • Build Ocelotl.

./maven_build.sh
  • If all is OK, upload the generated update site.
./upload_ocelotl.sh

Making a GitHub release

  • Go to the Ocelotl release page.
  • Press Draft a new release.
  • In the Tag version text field, specify the version tag in the format vx.y.z, where x.y.z must be the same as before.
  • In the Release title text field, specify the version name using the format vx.y.z, where x.y.z must be the same as before.
  • Optionally describe the release. A good practice is to summarize what has be done during the milestone using the title of its issues.
  • Press Publish Release.

Development workflow management

Internal contributions

  • The development tasks planned for Ocelotl are described as GitHub issues.
  • Different issues are grouped into milestones.
  • Milestones correspond to new releases.
  • Milestone names are the same as the tag that will be use for the GitHub release (e.g., vx.y.z).
  • The development of all the issues of a given milestone is done in a specific branch of the master. For example, the milestone Version 1.0.6 could be managed on a branch named milestone-1.0.6.
  • When an issue has been dealt with, some tests are done to verify that all is good and the issue is closed.
  • When all the issues of the milestone are closed, the following steps are done:
    • Some general tests are done to verify that all the issues of the milestone are actually done.
    • The user documentation (ocelotl.doc repository) is updated, if necessary.
    • The milestone branch is merged into the master and the branch is deleted.
    • The milestone is closed on GitHub and we can make a release.
  • Note: The master should always contain a stable version.

External contributions

External contributions (contributions from people not belonging to the soctrace-inria team) will follow the normal GitHub fork/pull-request procedure.