Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[JEP-305] Incrementals profiles #20

Merged
merged 11 commits into from
Apr 27, 2018
Merged

[JEP-305] Incrementals profiles #20

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
fa64385
[JENKINS-50692] Incrementals profiles.
jglick Apr 16, 2018
664b699
no-test-jar is not curretly defined for general components, so drop t…
jglick Apr 17, 2018
3dd6e2d
[JENKINS-50716] Flatten scm/tag.
jglick Apr 17, 2018
c886009
Moved incrementals.md from plugin-pom.
jglick Apr 17, 2018
19a8c00
More docs.
jglick Apr 17, 2018
83baf5b
Edits.
jglick Apr 17, 2018
4351ed1
Noting how other repositories get incrementalified.
jglick Apr 17, 2018
672850a
Updates.
jglick Apr 17, 2018
e831718
1.0-alpha-3
jglick Apr 18, 2018
afefab1
maven-hpi-plugin.version=2.3
jglick Apr 19, 2018
1e8819a
maven-help-plugin.version=3.0.1 so we can use help:evaluate -Doutput=…
jglick Apr 19, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
164 changes: 164 additions & 0 deletions incrementals.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,164 @@
# Incrementals

See [JEP-305](https:/jenkinsci/jep/blob/master/jep/305/README.adoc) for context.

## Usage in plugin POMs

Since most Jenkins repositories host plugins, this use case will be documented first.

### Enabling consumption of incrementals

If your plugin has (or may have) dependencies on incremental versions, run:

```bash
mkdir -p .mvn
echo -Pconsume-incrementals >> .mvn/maven.config
git add .mvn
```

(See [this guide](https://maven.apache.org/docs/3.3.1/release-notes.html#JVM_and_Command_Line_Options) for details on the `.mvn` directory.)

This profile merely activates access to the [Incrementals repository](https://repo.jenkins-ci.org/incrementals/).

### Enabling production of incrementals

To produce incremental artifacts _from_ your plugin, first edit your `pom.xml`.
If your plugin declares

```xml
<version>1.23-SNAPSHOT</version>
```

then replace that with

```xml
<version>${revision}${changelist}</version>
```

and then in the `<properties>` section add

```xml
<revision>1.23</revision>
<changelist>-SNAPSHOT</changelist>
```

If you have a multimodule reactor build, the new `properties` need be defined only in the root POM,
but every child POM should use the edited `version` to refer to its `parent`.
(It should _not_ override the `version`.)
Intermodule `dependency`es may use `${project.version}` to refer to the `version` of the sibling.

Also change

```xml
<scm>
<!-- … -->
<tag>HEAD</tag>
</scm>
```

to


```xml
<scm>
<!-- … -->
<tag>${scmTag}</tag>
</scm>
```

Now run

```bash
mkdir -p .mvn
echo -Pmight-produce-incrementals >> .mvn/maven.config
echo .flattened-pom.xml >> .gitignore
git add .mvn .gitignore
```

Finally, configure [git-changelist-maven-extension](https:/jglick/git-changelist-maven-extension) in `.mvn/extensions.xml`:

```xml
<extensions xmlns="http://maven.apache.org/EXTENSIONS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/EXTENSIONS/1.0.0 http://maven.apache.org/xsd/core-extensions-1.0.0.xsd">
<extension>
<groupId>io.jenkins.tools</groupId>
<artifactId>git-changelist-maven-extension</artifactId>
<version>1.0-alpha-3</version>
</extension>
</extensions>
```

Commit and push your edits.
Now if you are authorized to deploy to the Incrementals repository you could run:

```bash
mvn -Dset.changelist clean deploy
```

To produce equivalent artifacts in your local repository while working offline:

```bash
mvn -Dset.changelist -DskipTests clean install
```

If you do not select the `-Dset.changelist` option, you will create a regular `*-SNAPSHOT` artifact.
(And that is what you _must_ do if you have any local modifications or untracked files.)

### Running Maven releases

You may still use the Maven release plugin (MRP) when `might-produce-incrementals` is activated:

```bash
mvn -B release:{prepare,perform}
```

The released artifacts should have sensible metadata.
(You may notice that they deploy a “flattened” POM file, but this should not break anything.)
However, after performing a traditional release, to resume being able to produce incrementals you must run:

```bash
mvn help:evaluate -Dexpression=project.version -Doutput=version && \
mvn versions:set -Ddollar='$' -DnewVersion='${dollar}{revision}${dollar}{changelist}' -DgenerateBackupPoms=false && \
mvn versions:set-property -Dproperty=revision -DnewVersion=`sed -e 's/-SNAPSHOT$//' < version` -DgenerateBackupPoms=false && \
rm version
```

<!--- TODO JENKINS-50693 publish this as a packaged script somewhere --->

and commit and push the resulting `pom.xml` edits.

## Usage in other POMs

From repositories with POMs not inheriting from `org.jenkins-ci.plugins:plugin` you can follow similar steps to use Incrementals.
If you inherit from `org.jenkins-ci:jenkins`, the same profiles are available;
otherwise you will need to copy the definitions of the `consume-incrementals`, `might-produce-incrementals`, and `produce-incrementals` profiles from `org.jenkins-ci:jenkins`,
as well as the `incrementals.url` and `scmTag` properties,
into your parent POM or directly into your repository POM.
Some adjustment of `maven-enforcer-plugin` configuration may also be necessary.

## Offline testing

If you wish to test usage offline, run

```bash
docker run --rm --name nexus -p 8081:8081 -v nexus-data:/nexus-data sonatype/nexus3
```

add to your `~/.m2/settings.xml`:

```xml
<servers>
<server>
<id>incrementals</id>
<username>admin</username>
<password>admin123</password>
</server>
</servers>
```

and then add to command lines consuming or producing incremental versions:

```
-Dincrementals.url=http://localhost:8081/repository/maven-releases/
```

or define an equivalent profile in local settings.
129 changes: 119 additions & 10 deletions pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,10 +12,6 @@
<url>http://jenkins-ci.org/</url>
<inceptionYear>2004</inceptionYear>

<prerequisites>
<maven>2.2.1</maven>
</prerequisites>

<issueManagement>
<system>JIRA</system>
<url>http://issues.jenkins-ci.org</url>
Expand Down Expand Up @@ -638,9 +634,11 @@
<version>[3.3.9,)</version>
<message>3.3.9 is required at least.</message>
</requireMavenVersion>
<!-- TODO failing during incrementals deploy: MENFORCER-281
<requirePluginVersions>
<banSnapshots>false</banSnapshots>
</requirePluginVersions>
-->
<requireJavaVersion>
<version>[1.${java.level}.0,]</version>
</requireJavaVersion>
Expand Down Expand Up @@ -674,10 +672,6 @@
</plugin>
(or just override java.level) -->
</enforceBytecodeVersion>
<requireReleaseDeps>
<message>No Snapshots Allowed For Release Versions</message>
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

cf. jenkinsci/plugin-pom#100 (comment)

<onlyWhenRelease>true</onlyWhenRelease>
</requireReleaseDeps>
</rules>
</configuration>
</execution>
Expand Down Expand Up @@ -739,6 +733,118 @@
<maven.repository.update.freqency>always</maven.repository.update.freqency>
</properties>
</profile>
<profile> <!-- see JEP-305 -->
<id>consume-incrementals</id>
<repositories>
<repository>
<id>incrementals</id>
<url>${incrementals.url}</url>
<snapshots>
<enabled>false</enabled>
</snapshots>
</repository>
</repositories>
<pluginRepositories>
<pluginRepository>
<id>incrementals</id>
<url>${incrementals.url}</url>
<snapshots>
<enabled>false</enabled>
</snapshots>
</pluginRepository>
</pluginRepositories>
</profile>
<profile>
<id>might-produce-incrementals</id>
<build>
<plugins>
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>flatten-maven-plugin</artifactId>
<version>1.0.1</version>
<configuration>
<updatePomFile>true</updatePomFile>
</configuration>
<executions>
<execution>
<id>flatten</id>
<phase>process-resources</phase>
<goals>
<goal>flatten</goal>
</goals>
<configuration>
<flattenMode>oss</flattenMode>
</configuration>
</execution>
<execution>
<id>flatten.clean</id>
<phase>clean</phase>
<goals>
<goal>clean</goal>
</goals>
</execution>
</executions>
</plugin>
<plugin>
<artifactId>maven-enforcer-plugin</artifactId>
<executions>
<execution>
<id>display-info</id>
<configuration>
<rules>
<requireMavenVersion>
<version>[3.5.0,)</version>
<message>3.5.0+ required to use Incrementals.</message>
</requireMavenVersion>
</rules>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
</profile>
<profile>
<id>produce-incrementals</id>
<activation>
<property>
<name>set.changelist</name>
<value>true</value>
</property>
</activation>
<distributionManagement>
<repository>
<id>incrementals</id>
<url>${incrementals.url}</url>
</repository>
</distributionManagement>
<build>
<plugins>
<plugin>
<artifactId>maven-source-plugin</artifactId>
<executions>
<execution>
<id>attach-sources</id>
<goals>
<goal>jar</goal>
</goals>
</execution>
</executions>
</plugin>
<plugin>
<artifactId>maven-javadoc-plugin</artifactId>
<executions>
<execution>
<id>attach-javadocs</id>
<goals>
<goal>jar</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
</profile>
</profiles>

<properties>
Expand All @@ -765,6 +871,9 @@
Generally it is recommended to use @SuppressFBWarnings annotation unless you want to ignore an entire class of issues -->
<findbugs.excludeFilterFile />

<incrementals.url>https://repo.jenkins-ci.org/incrementals/</incrementals.url>
<scmTag>HEAD</scmTag>

<!-- Define all plugin versions as properties so individual hierarchies can easily override -->
<animal-sniffer-plugin.version>1.16</animal-sniffer-plugin.version>
<apt-maven-plugin.version>1.0-alpha-5</apt-maven-plugin.version>
Expand Down Expand Up @@ -793,8 +902,8 @@
<maven-eclipse-plugin.version>2.10</maven-eclipse-plugin.version>
<maven-enforcer-plugin.version>3.0.0-M1</maven-enforcer-plugin.version>
<maven-gpg-plugin.version>1.6</maven-gpg-plugin.version>
<maven-help-plugin.version>2.2</maven-help-plugin.version>
<maven-hpi-plugin.version>2.0</maven-hpi-plugin.version>
<maven-help-plugin.version>3.0.1</maven-help-plugin.version>
<maven-hpi-plugin.version>2.3</maven-hpi-plugin.version>
<maven-idea-plugin.version>2.2</maven-idea-plugin.version>
<maven-install-plugin.version>2.5.2</maven-install-plugin.version>
<maven-javadoc-plugin.version>3.0.0-M1</maven-javadoc-plugin.version>
Expand Down