Developers' Best Practices » History » Revision 6
Revision 5 (Alessia Bardi, 29/01/2014 11:38 AM) → Revision 6/20 (Alessia Bardi, 06/10/2014 02:30 PM)
h1. Developers' Best Practices
It is time for D-Net development teams to find a strategy to improve our developement work!
The introduction of Jenkins and Nexus helped a lot in terms of code management, but now it is time to establish a set of guidelines to better co-ordinate our teams.
The following best practices are inspired by CNR developers' common sense, so we do not assume they are written in stones and applies as they are also in your cases.
So, you are strongly invited to comment/update this wiki page, so that we can reach a consensus.
h2. Coding
Most of the D-Net modules have been migrated to from the old build system ant to maven. This implies some changes to the module directories and files, here's the migration guide:
http://ci.research-infrastructures.eu/public/docbook/MavenMigration.html
Maven compliant D-Net module structure:
<pre>
.
├── pom.xml
├── src
│ ├── main
│ │ ├── java
│ │ │ └── eu
│ │ │ └── dnetlib
│ │ └── resources
│ │ └── eu
│ │ └── dnetlib
│ └── test
│ ├── java
│ │ └── eu
│ │ └── dnetlib
│ └── resources
│ └── eu
│ └── dnetlib
└── target
└── classes
</pre>
Hint: consider to define the svn:ignore property, set on the module root
<pre>
cd <MODULE_NAME>
svn pe svn:ignore .
.classpath
.project
.settings
target
</pre>
h2. Branching
It is always recommended to create a new branch when performing heavy changes to a module, rather than directly into trunk.
h2. Use CI: trust Jenkins!
The developer should clean the @.m2/repository/eu@ local repository from time to time to be sure that there are no modules installed locally.
Modules should be downloaded from Nexus in order to properly resolve dependencies.
h2. Maven dependencies
For information about version conflict resolution with Maven3:
* http://docs.codehaus.org/display/MAVEN/Versioning
* https://cwiki.apache.org/confluence/display/MAVEN/Maven+3.x+Compatibility+Notes
Generally speaking, we suggest to use the keyword @LATEST@ to refer to the last available artifact (snapshot or release) for a module.
Keep in mind that Maven3 considers:
@1.0-alpha-1 < 1.0-beta-1 < 1.0-SNAPSHOT < 1.0 < 1.1-SNAPSHOT@
h2. Release Best Practices
h3. When/Why releasing a module?
* Generally speaking a developer should release a module when the code is mature enough to be used by others.
* An early release should be available in case others are relying on a module that is currently under heavy development (i.e., frequent commits that imply frequent snapshot updates), in order to avoid blocking other development activities.
* Before updating an interface (e.g., service interfaces) or library (e.g., common and utilities modules) a developer MUST ENSURE there is a release of the current version.
h3. How to change the assign a release version number number?
Before releasing a module, you must check which kinds of a snapshot?
changes have been performed since the last release.
@svn log@ is your friend here :) .
Depending on the kind of changes you can decide to increase the artifact version according to the following guidelines:
* BIG CHANGES impact the MAJOR version number. Ex. @0.0.1 --> 1.0.0@
** Examples of big changes are: updates to service interfaces, shared libraries, new functionalities.
* MINOR CHANGES impact the MINOR version number. Ex. @1.2.5 --> 1.3.0@
** Examples of minor changes are: service internals, non-shared code and libraries, important bug fixes.
* BUG FIXES impact the BUILD version number. Ex. @1.4.2 --> 1.4.3@
** Examples are small bug fixes that do not affect other components
h2. Release Best Practices
h3. When/Why releasing a module?
* Generally speaking a developer should release a module when the code is mature enough to be used by others.
* An early release should be available in case others are relying on a module that is currently under heavy development (i.e., frequent commits that imply frequent snapshot updates), in order to avoid blocking other development activities.
* Before updating an interface (e.g., service interfaces) or library (e.g., common and utilities modules) a developer MUST ENSURE there is a release of the current version.
h3. How to release?
These are the steps for the release of a module, given that developer has a fresh checkout of the module to be released.
# Add Ensure that the SCM info: module to be released and the modules depending on it compile fine on Jenkins (http://ci.research-infrastructures.eu/).
<pre> # Update and commit the version of the module (trunk) to be released according to the guidelines above.
This maven command can be helpful:
@mvn versions:set -DnewVersion={release_version}-SNAPSHOT@
<scm>
<developerConnection>scm:svn:https://svn.driver.research-infrastructures.eu/driver/dnet40/modules/{module_name}/trunk</developerConnection> # Copy the trunk source code to a release branch:
</scm> @svn cp https://svn.driver.../modules/{MODULE_NAME}/trunk https://svn.driver.../modules/{MODULE_NAME}/releases/{release_version}@
</pre> # Switch to the release branch:
@svn switch https://svn.driver.../modules/{MODULE_NAME}/releases/{release_version}@
# Set A released module MUST depend and inherit ONLY from released modules. Therefore the pom.xml file MUST be updated as follows:
## change the parent version to a released parent. Example: version. Current is 0.0.1-alpha.
<pre> ## change all snapshot dependencies to a released version. Ex. @0.2.3-SNAPSHOT --> 0.2.3@
<parent>
<groupId>eu.dnetlib</groupId>
<artifactId>dnet-parent</artifactId>
<version>1.0.0</version> ## change the artifact version by removing the @-SNAPSHOT@ suffix.
</parent> # Commit the updated pom.xml.
</pre>
# Ensure there are no snapshots included as dependencies. Snapshot dependencies won't be resolved anymore by maven because released parents have visibility only on the released repository (@dnet4-releases@). For example, if your module currently depends compiles: @mvn clean compile package -U@
# Create the release build job on
<pre> Jenkins (http://ci.research-infrastructures.eu/):
<dependency>
<groupId>eu.dnetlib</groupId>
<artifactId>cnr-misc-utils</artifactId>
<version>[1.0.0-SNAPSHOT,2.0.0-SNAPSHOT)</version> ## Select "New job"
</dependency>
</pre>
You should change ## Type in the dependency name of the job as follows:
@[module name]-release-[version]@. Ex. @dnet-runtime-release-0.0.9@
<pre> ## Select "Create from existing job" and type in @dnet-svn-template-release@, then press OK
<dependency>
<groupId>eu.dnetlib</groupId>
<artifactId>cnr-misc-utils</artifactId>
<version>[1.0.0,2.0.0)</version>
</dependency>
</pre>
Note ## Modify the repository URL so that this implies that it matches the dependency module (e.g. @cnr-misc-utils@) must have been released.
# Run @mvn release:prepare@ and answer the questions. Default answers are usually fine. This will:
#* copy your trunk into another svn public folder (@tags@) of the release branch:
#* update http://svn-public.driver.../modules/{MODULE_NAME}/releases/{release_version}
## Save, enable the versions in trunk and tags
# Run @mvn release:perform@. This will deploy job, start the job, watch it compile, ensure it is deployed on nexus, disable the job again (an artifact on Nexus in the release dnet-release repository @dnet4-releases@. cannot be overwritten, hence we disable the job just to be sure they are not fired again by mistake).
# Switch back to trunk:
@svn switch https://svn.driver.../modules/{MODULE_NAME}/trunk@
# Increase the build version number and commit the pom.xml. Example: if the version is @1.2.3-SNAPSHOT@ (it means that you've just released version @1.2.3@), increase the number to @1.2.4-SNAPSHOT@.
Possibly a script will be made available to cover the points from 2 to 7, 9, and 10.