@@ -21,3 +21,171 @@ For more information about Maven, see:
2121
2222* [ Learning Maven] ( http://developer.imagej.net/learning-maven )
2323* [ Maven FAQ] ( http://wiki.imagej.net/Maven_-_Frequently_Asked_Questions )
24+
25+ Adding a new project to pom-scijava
26+ ===================================
27+
28+ Including a project in pom-scijava is very beneficial. It means that a
29+ given pom-scijava version will be coupled with a specific version of
30+ that project, and by using the project.version properties, all
31+ consumers of pom-scijava will use only that version of the project.
32+
33+ It also minimizes bookkeeping, as whenever we run the Jenkins
34+ Bump-POM-SciJava job, the version property for each project is
35+ automatically updated to the latest release. By having a version property,
36+ there is no need to go through downstream projects updating their
37+ dependencies - a process that only invites mistakes.
38+
39+ There are several steps to include a project in pom-scijava, but they
40+ only need to be done once. The following tutorial will guide you through
41+ the process.
42+
43+ Preface
44+ -------
45+
46+ This tutorial assumes the project is a github project.
47+
48+ We will use these properties throughout the tutorial:
49+
50+ * PROPERTY
51+ * GROUPID
52+ * ARTIFACTID
53+ * VERSION
54+ * URL
55+ * KEY_NAME
56+
57+ The GROUPID and ARTIFACTID come directly from your project's pom.xml.
58+
59+ VERSION refers to the latest deployed version, and is the first version
60+ that will be included in pom-scijava (e.g. the only time you will manually set the version).
61+
62+ PROPERTY is the prefix for your project's properties. For example, SciJava-common
63+ uses the property "scijava-common". Thus when referencing SciJava-common properties via
64+ pom-scijava, you can use "scijava-common.version" or "scijava-common.groupId". This value
65+ can be anything you choose, but should be appropriate and unique to your project, to avoid
66+ clashing with other properties.
67+
68+ URL is the github url of your project.
69+
70+ KEY_NAME is the short name you give to your deploy key (see step 2).
71+
72+ 1 - Create a deploy key
73+ -----------------
74+
75+ First, as the jenkins user on dev.loci.wisc.edu, run:
76+
77+ ```
78+ ~/bin/add-github-deploy-key.sh KEY_NAME
79+ ```
80+
81+ to generate a SSH public/private key pair. Copy the public key fingerprint from
82+ this script's output for use later.
83+
84+ You will need to add this key in github to allow Jenkins access to your
85+ project. See the [ github help
86+ page] ( https://help.github.com/articles/managing-deploy-keys ) for instructions
87+ on setting up a deploy key. Use the following settings for your deploy key:
88+
89+ * Title: Jenkins@dev.imagejdev.org
90+ * Key: paste the public key fingerprint you copied earlier
91+
92+ Click "Add key" and go to the next step!
93+
94+ 2 - Update Pom-SciJava
95+ ----------------------
96+
97+ First make sure your SciJava-common is up to date.
98+
99+ In pom-scijava/pom.xml :
100+
101+ * Manually increase the minor ``` <version> ``` of the pom - e.g. ``` 1.32 ``` goes to ``` 1.33 ```
102+ * Find the ``` <properties> ``` block:
103+ * Add a comment block defining your project, e.g.
104+ ```
105+ <!-- project name - URL -->
106+ ```
107+ * If your project's groupId is not already defined, add an entry of the form:
108+ ```
109+ <PROPERTY.groupId>GROUPID</PROPERTY.groupId>
110+ ```
111+ * Add a version entry of the form:
112+ ```
113+ <PROPERTY.version>VERSION</PROPERTY.version>
114+ ```
115+
116+ Save and commit your changes.
117+
118+ 3 - Update bump-pom-scijava.sh
119+ ------------------------------
120+
121+ Again in the SciJava-common repository, edit the file:
122+
123+ bin/bump.pom-scijava.sh
124+
125+ There are two changes to make.
126+
127+ * First, search for:
128+
129+ ```
130+ test "a--default-properties"
131+ ```
132+
133+ In the following "set" block, add the line:
134+
135+ ```
136+ PROPERTY.version --latest
137+ ```
138+
139+ NB: Make sure all lines except the last of the set block are terminated with a backslash ('\') character.
140+
141+ * Second, search for:
142+
143+ ```
144+ if test "a--latest" = "a$value"
145+ ```
146+
147+ In the following "then" block, add the lines:
148+
149+ ```
150+ PROPERTY.version)
151+ ga=GROUPID:ARTIFACTID
152+ ;;
153+ ```
154+
155+ To ensure the bump-pom-scijava script sets the gav correctly for your project.
156+
157+ Save and commit your changes.
158+
159+ 4 - Update Jenkins
160+ ------------------
161+
162+ You will need someone to configure the [Bump-POM-SciJava](http://jenkins.imagej.net/view/SciJava/job/Bump-POM-SciJava/) job
163+ for you, if you do not have the rights to do so yourself.
164+
165+ Two changes need to be added here:
166+
167+ * First, in the Parameter section, use "Add Parameter -> Boolean Value". Name it "UPDATE_PROJECT" as appropriate for your
168+ project.
169+
170+ * Second, in the Build section under "Execute shell", search for:
171+
172+ ```
173+ CHILDREN=
174+ ```
175+
176+ At the end of this block, add these two lines:
177+
178+ ```
179+ test true != "$UPDATE_PROJECT" ||
180+ CHILDREN="$CHILDREN KEY_NAME:URL"
181+ ```
182+
183+ That's it! The next time Bump-POM-SciJava is run, there will be a check box for
184+ your project (however you named the UPDATE_PROJECT variable). Regardless if
185+ this box is checked or not, the base pom-scijava version for your project will
186+ be updated to the latest released. If the box is checked for a given project,
187+ then that project's parent pom will also be updated to the latest pom-scijava
188+ version.
189+
190+
191+
0 commit comments