Developers' Best Practices » History » Version 15
Alessia Bardi, 08/01/2015 02:17 PM
added commit step before mvn release:prepare
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 | 14 | Alessia Bardi | To merge the branch into trunk, you can follow this step by step tutorial: http://www.sepcot.com/blog/2007/04/SVN-Merge-Branch-Trunk |
56 | |||
57 | 2 | Claudio Atzori | h2. Use CI: trust Jenkins! |
58 | 1 | Alessia Bardi | |
59 | The developer should clean the @.m2/repository/eu@ local repository from time to time to be sure that there are no modules installed locally. |
||
60 | |||
61 | Modules should be downloaded from Nexus in order to properly resolve dependencies. |
||
62 | |||
63 | 5 | Alessia Bardi | h2. Maven dependencies |
64 | |||
65 | For information about version conflict resolution with Maven3: |
||
66 | * http://docs.codehaus.org/display/MAVEN/Versioning |
||
67 | * https://cwiki.apache.org/confluence/display/MAVEN/Maven+3.x+Compatibility+Notes |
||
68 | |||
69 | Generally speaking, we suggest to use the keyword @LATEST@ to refer to the last available artifact (snapshot or release) for a module. |
||
70 | Keep in mind that Maven3 considers: |
||
71 | @1.0-alpha-1 < 1.0-beta-1 < 1.0-SNAPSHOT < 1.0 < 1.1-SNAPSHOT@ |
||
72 | |||
73 | 6 | Alessia Bardi | h3. How to change the version number of a snapshot? |
74 | 1 | Alessia Bardi | |
75 | Depending on the kind of changes you can decide to increase the artifact version according to the following guidelines: |
||
76 | * BIG CHANGES impact the MAJOR version number. Ex. @0.0.1 --> 1.0.0@ |
||
77 | ** Examples of big changes are: updates to service interfaces, shared libraries, new functionalities. |
||
78 | * MINOR CHANGES impact the MINOR version number. Ex. @1.2.5 --> 1.3.0@ |
||
79 | ** Examples of minor changes are: service internals, non-shared code and libraries, important bug fixes. |
||
80 | * BUG FIXES impact the BUILD version number. Ex. @1.4.2 --> 1.4.3@ |
||
81 | ** Examples are small bug fixes that do not affect other components |
||
82 | |||
83 | 6 | Alessia Bardi | h2. Release Best Practices |
84 | |||
85 | h3. When/Why releasing a module? |
||
86 | |||
87 | * Generally speaking a developer should release a module when the code is mature enough to be used by others. |
||
88 | * 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. |
||
89 | 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. |
90 | 6 | Alessia Bardi | |
91 | 1 | Alessia Bardi | h3. How to release? |
92 | |||
93 | 13 | Alessia Bardi | Note that the maven release plugin works fine with *Apache Maven 3.0.5* and that is the version that we suggest you to use. |
94 | To know which maven version you are using run: <pre>mvn -version</pre> |
||
95 | If you have a newer version (e.g. 3.2.3), then you'll get the error @Return code is: 400, ReasonPhrase: Bad Request@ when running @mvn release:perform@. |
||
96 | However +the jar should have been correctly deployed+: we strongly suggest you to check this is true by logging into our "Nexus":http://maven.research-infrastructures.eu/nexus. |
||
97 | |||
98 | 1 | Alessia Bardi | These are the steps for the release of a module, given that developer has a fresh checkout of the module to be released. |
99 | 13 | Alessia Bardi | |
100 | 11 | Alessia Bardi | # Add the following at the beginning of your @~/.m2/settings.xml@: |
101 | 8 | Alessia Bardi | <pre> |
102 | <servers> |
||
103 | <server> |
||
104 | <id>dnet4-releases</id> |
||
105 | <username>your LDAP username</username> |
||
106 | <password>your LDAP password</password> |
||
107 | </server> |
||
108 | </servers> |
||
109 | </pre> |
||
110 | 7 | Alessia Bardi | # Add the SCM info (change @{project.name}@ with the actual name of the project): |
111 | 6 | Alessia Bardi | <pre> |
112 | <scm> |
||
113 | 7 | Alessia Bardi | <developerConnection>scm:svn:https://svn.driver.research-infrastructures.eu/driver/dnet40/modules/{project.name}/trunk</developerConnection> |
114 | 6 | Alessia Bardi | </scm> |
115 | </pre> |
||
116 | # Set the parent to a released parent. Example: |
||
117 | <pre> |
||
118 | <parent> |
||
119 | <groupId>eu.dnetlib</groupId> |
||
120 | <artifactId>dnet-parent</artifactId> |
||
121 | <version>1.0.0</version> |
||
122 | </parent> |
||
123 | </pre> |
||
124 | # 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 |
||
125 | <pre> |
||
126 | <dependency> |
||
127 | <groupId>eu.dnetlib</groupId> |
||
128 | <artifactId>cnr-misc-utils</artifactId> |
||
129 | <version>[1.0.0-SNAPSHOT,2.0.0-SNAPSHOT)</version> |
||
130 | </dependency> |
||
131 | </pre> |
||
132 | You should change the dependency as follows: |
||
133 | <pre> |
||
134 | <dependency> |
||
135 | <groupId>eu.dnetlib</groupId> |
||
136 | <artifactId>cnr-misc-utils</artifactId> |
||
137 | <version>[1.0.0,2.0.0)</version> |
||
138 | </dependency> |
||
139 | </pre> |
||
140 | Note that this implies that the dependency module (e.g. @cnr-misc-utils@) must have been released. |
||
141 | 15 | Alessia Bardi | # Commit the changes you made in the pom.xml |
142 | 6 | Alessia Bardi | # Run @mvn release:prepare@ and answer the questions. Default answers are usually fine. This will: |
143 | #* copy your trunk into another svn folder (@tags@) |
||
144 | #* update the versions in trunk and tags |
||
145 | # Run @mvn release:perform@. This will deploy the artifact on Nexus in the release repository @dnet4-releases@. |
||
146 | 8 | Alessia Bardi | |
147 | 12 | Alessia Bardi | If you experience any issue, open a ticket to CNR. |