Source Code Management

• General Organisation
• How to Make a New Internal Delivery (i.e. tagging and branching)
  • Check that All the Code is Committed
    • Update the Version Number in the pom.xml
    • Command Line
    • Using Netbeans
  • Create an Annotated Tag
    • Command Line
    • Netbeans
  • Checkout a Tagged Version
  • Create a Maintenance Branch
    • Command Line
    • Netbeans
• Maven Central Deployment
  • Summary
  • Prerequisites
  • Deployment
  • Troubleshooting
  • References

General Organisation

• master is for the day-to-day development, i.e. the version in master is a work-in-progress version;
• whenever a work-in-progress version is judged as stable enough, it can be:
  • tagged.
  • branched if some bug-correction is required for the delivered version.

How to Make a New Internal Delivery (i.e. tagging and branching)

Note: this part applies for deliveries internal to the development team. They do not cover (even if they are strongly related to) the [delivery of the artefacts on Maven Central].

In the following, ${CORESE_ROOT} is the root directory of the Corese source code.

Check that All the Code is Committed

Update the Version Number in the pom.xml

Do not forget to update the file pom.xml files: the <version>...</version> parts must be changed to an expression of the form: <version>x.y.z[-SNAPSHOT]</version> where

• x.y.z stands for the version number;

• the presence of optional -SNAPSHOT suffix changes which deployment server will be used.

• If the version is a snapshot (i.e. the version is suffixed with -SNAPSHOT), then the repository described in the snapshotRepository section will be used.

• If the version is not a snapshot, then the repository described at the<repository> section will be used.

Command Line

1. in the directory you installed Corese, run the command git status.
2. Check that:

• there is no modified file remaining. If that is the case, commit them.
• if there are untracked files, should they be added to the source code repository?
  • if the answer is yes, then use git add and git commit;
  • if the answer is no, consider to add the files in .gitignore so that they are no more displayed

Using Netbeans

1. Open the git commit window by either:

• using the menu entry "Team/Commit"
• using the right-click entry "Git/Commit"

2. Note that by default, Netbeans set all the files added or modified a being selected for the current commit. If you prefer to make several commits instead (e.g. to clearly separate the addition of several functionalities), you have to unselect the files to commit later.

Create an Annotated Tag

• Note that a tag in git is only a pointer to a given version. If modifications are required, for example caused by maintenance of the tagged version, then a branch has to be created: see [how to create a maintenance branch](# Create a Maintenance Branch)
• tags are not automatically pushed, so it has to be specified.

Command Line

To create an annotated tag num_version:

`cd ${CORESE_ROOT} && git tag -a num_version`
`git push --tags`

Netbeans

Open the creation tag dialog box either by:

1. using the entry in the menu "Team / Branch/Tag / Create Tag..."
2. using the right-click menu "Git / Branch/Tag / Create Tag...".

Both menus open the following dialog box, where the name of the tag and a message must be provided.

In order to push the newly created tag, use one of the two following menus:

1. in the main menu bar: "Team/Remote/Push..."
2. in the right-click menu: "Git/Remote/Push..."

It opens a dialog box: Click on "Next".

In this panel, you must specify which tag has to be pushed: they have the prefix "tags/..." and note the [A] to indicate it will add the tag to the remote repository. Select the tag that has been added.

The third panel is not displayed here: you only should have to launch the push by clicking on "Finish".

Checkout a Tagged Version

Be careful: when a tagged version is obtained using the command git checkout num_version, the directory is put in a detached branch. It is sufficient to peer at the state of the state for a given version, but if modifications have to be made to the code, you should create a "maintenance branch", as is described in the next section.

Create a Maintenance Branch

Command Line

The following command:

1. creates a branch named branch num_version;
2. the new branch contains the code as for the version num_version;
3. the local repository, i.e. your directory, is switched to the new branch.

git branch -b branch num_version

If you are unsure of the branch currently active, it can be known with the command git branch.

Netbeans

• In order to see the current branch for your repository, check that "View/Show Versioning Labels" is set. It displays in the "Projects" panel the current branch for any versioned project.

• Open the dialog for branch creation either using:

  1. the menu "Team / Branch/Tag / Create Branch"
  2. the right-click menu "Git / Branch/Tag / Create Branch".

Both open the following dialog box:

Enter:

1. the name of the tag that has been given to the version you are interested for;
2. create a branch tracking the modifications that will be made to this tagged version.
   Note that if you plan no modification of the tagged version, it is not necessary to create a new branch. Just be conscious that the local repository will be in "detached" branch, requiring to be careful if finally modifications are made.

Maven Central Deployment

Summary

The purpose of this section is to explain how to export "artefacts" of the project, so they can be easily downloaded and used. Each Corese module is distributed through 3 jars binaries, sources and javadoc), all being signed. The deploimenet made by maven depends on the version number given to the project:

• if the version number ends with "-SNAPSHOT", for a work-in-progress version, the deployment will be done only on snapshots repository.
• otherwise, the version is considered as being a stable version, and the deployment is made in two steps:
  • a validation step on the sonatype server, where the packages are checked against various criteria (metadata, that all required jars are present and signed, etc.);
  • if the validation step succeeds, the artefacts are uploaded to Maven Central after 10 minutes.

Note: the OSSRH server used for the deployment is a "trusted server". Another one could be used (maybe the one on Nyxe, once updated, could do the job).

Prerequisites

From the sonatype documentation, only the GPG/PGP key has to be set up individually. The other requirements should already be setup in the Corese project.

• Create a JIRA account on OSSRH.
  • to be added in an existing repository: ask to be added as a new maintainer to the repositories fr.inria.corese adding a comment to this tickets.
  • to create a new repository.
• Configure GPG key.
  • intallation, creation of public and private keys (see this documentation).
  • configure Maven (see this documentation).

Deployment

Requires around 10 minutes before being fully effective on Central

mv clean deploy -P maven-central-release

Troubleshooting

Maven logs are usually self-explanatory, even if sometimes long and verbose.
Look carefully to the report on the validating site. It can be easier to read the report on https://oss.sonatype.org/#stagingProfiles .

It is possible to check whether the artefacts where correctly uploaded event before the maven central search engine has been updated, by looking directly in the artefact repository at : https://repo1.maven.org/maven2/fr/inria/corese/ .

References

• http://central.sonatype.org/pages/requirements.html
• http://central.sonatype.org/pages/apache-maven.html