Project

General

Profile

Developers' Best Practices » History » Version 11

Alessia Bardi, 27/10/2014 11:10 AM
Added missing @

1 1 Alessia Bardi
h1. Developers' Best Practices
2
3 3 Claudio Atzori
It is time for D-Net development teams to find a strategy to improve our developement work!
4 1 Alessia Bardi
5
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.
6
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.
7
8
So, you are strongly invited to comment/update this wiki page, so that we can reach a consensus. 
9 3 Claudio Atzori
10
h2. Coding
11
12
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: 
13
http://ci.research-infrastructures.eu/public/docbook/MavenMigration.html
14
15
Maven compliant D-Net module structure:
16
17
<pre>
18
.
19
├── pom.xml
20
├── src
21
│   ├── main
22
│   │   ├── java
23
│   │   │   └── eu
24
│   │   │       └── dnetlib
25
│   │   └── resources
26
│   │       └── eu
27
│   │           └── dnetlib
28
│   └── test
29
│       ├── java
30
│       │   └── eu
31
│       │       └── dnetlib
32
│       └── resources
33
│           └── eu
34
│               └── dnetlib
35
└── target
36
    └── classes
37
</pre>
38
39
Hint: consider to define the svn:ignore property, set on the module root
40
41
<pre>
42
cd <MODULE_NAME>
43
svn pe svn:ignore .
44
45
.classpath
46
.project
47
.settings
48
target 
49
</pre>
50 1 Alessia Bardi
51
h2. Branching
52
53
It is always recommended to create a new branch when performing heavy changes to a module, rather than directly into trunk.
54
55 2 Claudio Atzori
h2. Use CI: trust Jenkins!
56 1 Alessia Bardi
57
The developer should clean the @.m2/repository/eu@ local repository from time to time to be sure that there are no modules installed locally. 
58
59
Modules should be downloaded from Nexus in order to properly resolve dependencies.
60
61 5 Alessia Bardi
h2. Maven dependencies
62
63
For information about version conflict resolution with Maven3:
64
* http://docs.codehaus.org/display/MAVEN/Versioning
65
* https://cwiki.apache.org/confluence/display/MAVEN/Maven+3.x+Compatibility+Notes
66
67
Generally speaking, we suggest to use the keyword @LATEST@ to refer to the last available artifact (snapshot or release) for a module.
68
Keep in mind that Maven3 considers:
69
@1.0-alpha-1 < 1.0-beta-1 < 1.0-SNAPSHOT < 1.0 < 1.1-SNAPSHOT@
70
71 6 Alessia Bardi
h3. How to change the version number of a snapshot?
72 1 Alessia Bardi
73
Depending on the kind of changes you can decide to increase the artifact version according to the following guidelines:
74
* BIG CHANGES impact the MAJOR version number. Ex. @0.0.1 --> 1.0.0@
75
** Examples of big changes are: updates to service interfaces, shared libraries, new functionalities.
76
* MINOR CHANGES impact the MINOR version number. Ex. @1.2.5 --> 1.3.0@
77
** Examples of minor changes are: service internals, non-shared code and libraries, important bug fixes.
78
* BUG FIXES impact the BUILD version number. Ex. @1.4.2 --> 1.4.3@
79
** Examples are small bug fixes that do not affect other components 
80
81 6 Alessia Bardi
h2. Release Best Practices
82
83
h3. When/Why releasing a module?
84
85
* Generally speaking a developer should release a module when the code is mature enough to be used by others. 
86
* 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.
87 7 Alessia Bardi
* 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.
88 6 Alessia Bardi
89 1 Alessia Bardi
h3. How to release?
90
91
These are the steps for the release of a module, given that developer has a fresh checkout of the module to be released.
92 11 Alessia Bardi
# Add the following at the beginning of your @~/.m2/settings.xml@:
93 8 Alessia Bardi
<pre>
94
<servers>
95
 <server>
96
      <id>dnet4-releases</id>
97
      <username>your LDAP username</username>
98
      <password>your LDAP password</password>
99
   </server>
100
</servers>
101
</pre>
102 7 Alessia Bardi
# Add the SCM info (change @{project.name}@ with the actual name of the project):
103 6 Alessia Bardi
<pre>
104
<scm>
105 7 Alessia Bardi
   <developerConnection>scm:svn:https://svn.driver.research-infrastructures.eu/driver/dnet40/modules/{project.name}/trunk</developerConnection>
106 6 Alessia Bardi
</scm>
107
</pre>
108
# Set the parent to a released parent. Example:
109
<pre>
110
<parent>
111
   <groupId>eu.dnetlib</groupId>
112
   <artifactId>dnet-parent</artifactId>
113
   <version>1.0.0</version>
114
</parent>
115
</pre>
116
# 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 on 
117
<pre>
118
<dependency>
119
	<groupId>eu.dnetlib</groupId>
120
	<artifactId>cnr-misc-utils</artifactId>
121
	<version>[1.0.0-SNAPSHOT,2.0.0-SNAPSHOT)</version>
122
</dependency>
123
</pre>
124
You should change the dependency as follows:
125
<pre>
126
<dependency>
127
	<groupId>eu.dnetlib</groupId>
128
	<artifactId>cnr-misc-utils</artifactId>
129
	<version>[1.0.0,2.0.0)</version>
130
</dependency>
131
</pre>
132
Note that this implies that the dependency module (e.g. @cnr-misc-utils@) must have been released.
133
# Run @mvn release:prepare@ and answer the questions. Default answers are usually fine. This will:
134
#* copy your trunk into another svn folder (@tags@) 
135
#* update the versions in trunk and tags
136
# Run @mvn release:perform@. This will deploy the artifact on Nexus in the release repository @dnet4-releases@.
137 8 Alessia Bardi
138
If you experience any issue, open a ticket to CNR or write to dnet-team@isti.cnr.it