Skip to content

Commit 8d03c63

Browse files
dr0idr0i
committed
Merge #727 from branch '709-addHowToMaintainUsingCentralSonatype'
2 parents 1535504 + e7154ce commit 8d03c63

2 files changed

Lines changed: 102 additions & 101 deletions

File tree

‎MAINTAINING.md‎

Lines changed: 96 additions & 99 deletions
Original file line numberDiff line numberDiff line change
@@ -25,13 +25,13 @@ Merge pull-request #PULLREQUEST-ID from cboehme/fix-xy
2525
# Releasing
2626

2727
We shall make releases quarterly. Approximate timetable is every Januar, April, July, October.
28-
We may publish `master-SNAPSHOT` builds more frequently.
2928

3029
Releasing involves to first make and test the release candidate before actually making the release. Note that we provide a *GitHub release for manual download* as well as a *release on Maven central* to be consumed as a library.
3130

32-
It's good habit to use semantic versioning in release numbers `A`.`B`.`C`, i.e. increase `A` when it's a major release breaking backward compatibility; increase `B` when it got new features; increase `C` indicating bug-fixes. A suffix like `rcN` (where `N` is a number) indicates a release candidate (`rc`).
31+
It's good habit to use semantic versioning in release numbers `A`.`B`.`C`, i.e. increase `A` when it's a major release breaking backward compatibility; increase `B` when it got new features; increase `C` indicating bug-fixes.
3332

34-
To upload to Sonatype you need (as well for the release candidate as for the release) a `gradle.properties` in the root directory that looks like this:
33+
## Signing
34+
To upload to Sonatype we need to sign the artifacts. Adjust `gradle.properties` in the root directory that like this:
3535

3636
```
3737
signing.gnupg.executable=gpg
@@ -40,134 +40,131 @@ signing.gnupg.homeDir=$e.g."~/.gnupg"
4040
signing.gnupg.keyName=$yourKeyName
4141
signing.password=$keysPassphrase
4242
# depending on gradle plugin versions etc. you may need to use:
43-
# signing.keyId=$yourKeyName
44-
# signing.secretKeyRingFile=$e.g."~/.gnupg/secring.gpg"
45-
# Go to https://s01.oss.sonatype.org/
46-
# Go to profile
47-
# Change the pulldown from “Summary” to “User Token”
48-
# Click on “Access User Token”
49-
sonatypeUsername=$usernameOfAccessUserToken
50-
sonatypePassword=$token
43+
signing.keyId=$yourKeyName
44+
signing.secretKeyRingFile=$e.g."~/.gnupg/secring.gpg"
5145
```
5246

53-
## Publish `master-SNAPSHOT` builds
47+
## Authorize at central sonatype
5448

55-
These are done more often, in irregular intervals. They are not considered stable and may break your application, so be cautious when using them.
49+
To be able to authorize at central.sonatype you first have to "Generate User
50+
Token" at https://central.sonatype.com/usertoken (must be logged in). Copy/add the
51+
snippet you will be provided when creating the token to `~/.m2/settings.xml`.
5652

57-
The process is identical to making a release candidate, but without making any tags:
53+
!This is also needed when testing the uploaded deployment bundle (see below).!
5854

59-
1. Switch to the `master` branch:
60-
```
61-
git switch master
62-
```
63-
1. Proceed as described in [Release candidate - Upload to Sonatype](#upload-to-sonatype), but omit the `publishVersion` parameter in order to build and upload the `master-SNAPSHOT`.
55+
## Authorize the nexus publishing plugin
6456

65-
## Release candidate
57+
According to the [nexus
58+
plugin](https://github.com/gradle-nexus/publish-plugin?tab=readme-ov-file#publishing-to-maven-central-via-sonatype-central)
59+
you have to add the following to the `gradle.properties`:
6660

67-
*Release candidates should be tested by different people before releasing!*
61+
```
62+
sonatypeUsername=$usernameOfToken
63+
sonatypePassword=$passwordOfToken
64+
```
6865

69-
### Prepare your release candidate
66+
## Upload, test, publish a release
7067

71-
1. Make an annotated signed tag for the release candidate (necessary for Gradle to pick up the proper name):
72-
```
73-
git tag -s metafacture-core-A.B.C-rcN
74-
```
75-
1. When prompted, add a sensible commit message. For instance, something like:
68+
There are no more "Release candidates" as such, but the uploaded, validated
69+
[deployment bundle can be
70+
tested](https://central.sonatype.org/publish/publish-portal-api/#manually-testing-a-deployment-bundle).
71+
I.e. you first upload a release and before publishing it you test it.
72+
73+
### Upload
74+
75+
a) It's going from your local Git repository to central.sonatype.com to Maven Central. Each station requires some manual actions so you can double check that everything is ok. b) A release should also be published to GitHub.
76+
77+
1. Make an annotated signed tag for the release:
7678
```
77-
Release candidate 5.7.0
79+
git tag -s metafacture-core-A.B.C
7880
```
79-
1. Optionally, you can now test the build locally by invoking a Gradle target:
81+
1. When prompted, add a sensible tag message. For instance, something like:
8082
```
81-
./gradlew assemble -PpublishVersion=A.B.C-rcN
83+
Release A.B.C
8284
```
83-
84-
### Upload to Sonatype
85-
8685
1. Make sure to have a *clean* Git directory (otherwise the build will fail with the error message `Working copy has modifications`):
8786
```
8887
git status
8988
```
90-
1. Now you can build and upload the release candidate to Sonatype (note that `./gradlew` should inform you to make a "snapshot build". If the version doesn't end with `-SNAPSHOT` the artifacts will not be uploaded to Sonatype's snapshot repository!):
91-
```
92-
./gradlew publishToSonatype -PpublishVersion=A.B.C-rcN
93-
```
94-
1. Go to [Sonatype's snapshot repository](https://oss.sonatype.org/index.html#nexus-search;gav~org.metafacture) and type in the correct `Version` to see if it is already available there (can take some minutes). [Example for `5.5.1-rc1-SNAPSHOT`](https://oss.sonatype.org/index.html#nexus-search;gav~org.metafacture~~5.5.1*~~)(if you don't see a `5.5.1-rc1-SNAPSHOT.jar` there check it at https://oss.sonatype.org/content/repositories/snapshots/org/metafacture/metafacture-biblio/5.5.1-rc1-SNAPSHOT/).
95-
96-
### Publish to [GitHub Packages](https://github.com/orgs/metafacture/packages?repo_name=metafacture-core)
97-
98-
1. Push the annotated signed tag to GitHub:
89+
1. Now you can build and upload the release to Sonatype:
9990
```
100-
git push origin tag metafacture-core-A.B.C-rcN
91+
./gradlew publishToSonatype -PpublishVersion=A.B.C closeSonatypeStagingRepository
10192
```
102-
The publishing to GitHub packages is triggered then via the GitHub Actions workflow.
93+
### Test
10394
104-
Note that `Packages` is not the same as [`Releases`](https://github.com/metafacture/metafacture-core/releases).
95+
_As a fallback and for build systems where the below does not work:
96+
git checkout the release tag resp. the branch, build locally and consume locally. You don't need
97+
to have a login then, no special configs etc._
10598
106-
### Consume the SNAPSHOT
99+
If you decide to test what is actually in the pipeline you need some
100+
prerequisites;
101+
You need to have a login at central.sonatype.com and be added as a
102+
maintainer of the namespace `org.metafacture`.
103+
Follow the section "Authorize at central sonatype" to be able to test the
104+
deployment bundle.
107105
108-
1. See e.g. [5.5.1-rc1-SNAPSHOT](https://oss.sonatype.org/index.html#nexus-search;gav~org.metafacture~~5.5.1*~~) for how to configure the dependency.
109-
1. Configure your build system to use Sonatype's Snapshot Repository to be able to load the dependencies of the release candidate (or `master-SNAPSHOT`).
110-
For Maven update your `pom.xml` (after `</dependencies>`):
111-
```xml
112-
<repositories>
106+
You have to add this into you `~/.m2/settings.xml`:
107+
```
108+
<servers>
109+
<server>
110+
<id>central.manual.testing</id>
111+
<configuration>
112+
<httpHeaders>
113+
<property>
114+
<name>Authorization</name>
115+
<value>Bearer $basencodedUsernameAndPassword</value>
116+
</property>
117+
</httpHeaders>
118+
</configuration>
119+
</server>
120+
</servers>
121+
122+
<profiles>
123+
<profile>
124+
<id>central.manual.testing</id>
125+
<repositories>
113126
<repository>
114-
<id>oss.sonatype.org-snapshot</id>
115-
<url>https://oss.sonatype.org/content/repositories/snapshots</url>
116-
<releases>
117-
<enabled>false</enabled>
118-
</releases>
119-
<snapshots>
120-
<enabled>true</enabled>
121-
</snapshots>
127+
<id>central.manual.testing</id>
128+
<name>Central Testing repository</name>
129+
<url>https://central.sonatype.com/api/v1/publisher/deployments/download</url>
122130
</repository>
123-
</repositories>
124-
```
125-
For Gradle, add the snapshots repository:
126-
```gradle
127-
repositories {
128-
maven { url 'https://oss.sonatype.org/content/repositories/snapshots' }
129-
}
130-
```
131-
For Leiningen, add this to your `project.clj` (and be aware of the proper indentation!):
132-
```clojure
133-
:repositories [["snapshots" "https://oss.sonatype.org/content/repositories/snapshots"]]
134-
```
135-
For sbt, add this to your `build.sbt`:
136-
```
137-
resolvers += "Sonatype OSS Snapshots" at "https://oss.sonatype.org/content/repositories/snapshots"
138-
```
131+
</repositories>
132+
</profile>
133+
</profiles>
134+
```
135+
where `basencodedUsernameAndPassword` is created like this:
136+
```
137+
printf "$usernameToken:$passwordToken" | base64
138+
```
139+
(note the semicolon `:`).
139140
140-
## Making a release
141+
If you have a maven project you can now update the dependencies in the
142+
`pom.xml` and download the like:
141143
142-
a) It's going from your local Git repository to Sonatype to Maven Central. Each station requires some manual actions so you can double check that everything is ok. b) A release should also be published to GitHub.
144+
```
145+
mvn -debug -Pcentral.manual.testing install
146+
```
143147
144-
1. Ensure that the approved release candidate tag exactly matches `master` (should output `metafacture-core-A.B.C-rcN`):
145-
```
146-
git switch master; git describe --tags --exact-match
147-
```
148-
1. Make an annotated signed tag for the release:
149-
```
150-
git tag -s metafacture-core-A.B.C
151-
```
152-
1. When prompted, add a sensible commit message. For instance, something like:
153-
```
154-
Release 5.7.0
155-
```
156-
1. Push the annotated signed tag to GitHub:
148+
### Publish
149+
150+
If the tests went well we can publish.
151+
We publish the Metafacture libraries as modules to maven central and a
152+
Metafactur standalone runner at GitHub releases.
153+
154+
#### Publish Metafacture Runner to Github Releases
155+
156+
This provides the standalone runner.
157+
158+
1. Push the annotated signed tag you have created in the "Upload" section to GitHub:
157159
```
158160
git push origin metafacture-core-A.B.C
159161
```
160-
1. Make sure to have a *clean* Git directory (otherwise the build will fail with the error message `Working copy has modifications`):
161-
```
162-
git status
163-
```
164162
1. Now the tag is available on GitHub. You can manually choose to [draft a new release on GitHub](https://github.com/metafacture/metafacture-core/releases/new). The signed `*-dist.*` files must be uploaded manually. They are produced like this:
165163
```
166164
./gradlew metafacture-runner:signArchive -PpublishVersion=A.B.C
167165
```
168166
and can be found in `metafacture-runner/build/distributions/` (don't mind the `Source code` for that is created by GitHub automatically).
169-
1. Now you can build and upload the release to Sonatype:
170-
```
171-
./gradlew publishToSonatype -PpublishVersion=A.B.C
172-
```
173-
1. Finally, go to [oss.sonatype.org](https://oss.sonatype.org), log in, check the [Staging Repositories](https://oss.sonatype.org/#stagingRepositories) and when it's finished, click on `Close`. If everything is good, publish with clicking on `Release` - attention, because once published it can't be removed. The artifacts are uploaded to Maven Central (which may take some time; have a look at e.g. [metafacture-biblio](https://repo1.maven.org/maven2/org/metafacture/metafacture-biblio/)). You can check that it's actually in the publishing pipeline by clicking on `Views/Repositories->Releases`, then type in the `Path lookup` field `org/metafacture/` and click on version.
167+
168+
#### Publish to Maven Central
169+
170+
1. Finally, go to [central.sonatype.com](https://central.sonatype.com/publishing), log in, check the namespace (if you maintain more than one repo). Attention, because once published it can't be removed. If sure, click on "Publish". The artifacts are uploaded to Maven Central (which may take some time; have a look at e.g. [metafacture-biblio](https://repo1.maven.org/maven2/org/metafacture/metafacture-biblio/)).i

‎build.gradle‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ plugins {
2121
//id 'org.ec4j.editorconfig' version '0.0.3'
2222
id 'org.sonarqube' version '2.6.2'
2323
id 'org.xtext.builder' version '4.0.0'
24-
id 'io.github.gradle-nexus.publish-plugin' version '1.3.0'
24+
id 'io.github.gradle-nexus.publish-plugin' version '2.0.0'
2525
}
2626

2727
subprojects {
@@ -316,7 +316,11 @@ sonarqube {
316316

317317
nexusPublishing {
318318
repositories {
319-
sonatype ()
319+
// see https://central.sonatype.org/publish/publish-portal-ossrh-staging-api/#configuration
320+
sonatype {
321+
nexusUrl.set(uri("https://ossrh-staging-api.central.sonatype.com/service/local/"))
322+
snapshotRepositoryUrl.set(uri("https://central.sonatype.com/repository/maven-snapshots/"))
323+
}
320324
}
321325
}
322326

0 commit comments

Comments
 (0)