Skip to content

Commit 60f8e4e

Browse files
dr0idr0i
committed
Merge #591 from branch 'addMaintaining.md' of github.com:metafacture/metafacture-core
2 parents 1a5e003 + d3c7969 commit 60f8e4e

File tree

2 files changed

+192
-1
lines changed

2 files changed

+192
-1
lines changed

‎CONTRIBUTING.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -173,4 +173,4 @@ The *Definition of Done* describes a list of criteria which issues have to meet
173173

174174
### Releasing Metafacture
175175

176-
Follow the [wiki's Maintainer-Guidelines](https://github.com/metafacture/metafacture-core/wiki/Maintainer-Guidelines).
176+
Follow the [MAINTAINING.md](https://github.com/metafacture/metafacture-core/blob/master/MAINTAINING.md).

‎MAINTAINING.md

Lines changed: 191 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,191 @@
1+
# Merging pull requests
2+
3+
Pull requests should not be rebased (as this would rewrite Git's history) but merged with the the latest master and merge as a none fast-forward merge into master.
4+
For example, to merge a pull request `fix-xy` from http://github.com/cboehme/metafacture-core the following Git commands should be used:
5+
```
6+
# Bring master up-to-date:
7+
git checkout master
8+
git fetch
9+
git rebase
10+
# Fetch pull request:
11+
git fetch http://github.com/cboehme/metafacture-core.git +fix-xy:cboehme-fix-xy
12+
git checkout cboehme-fix-xy
13+
# Merge master:
14+
git merge master
15+
# Run test cases, check commit, add fixup commits ...
16+
# Merge into master
17+
git checkout master
18+
git merge --no-ff cboehme-fix-xy
19+
```
20+
The commit message of the merge command should follow this format:
21+
```
22+
Merge pull-request #PULLREQUEST-ID from cboehme/fix-xy
23+
```
24+
25+
# Releasing
26+
27+
We shall make releases quarterly. Approximate timetable is every Januar, April, July, October.
28+
We may publish `master-SNAPSHOT` builds more frequently.
29+
30+
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.
31+
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`).
33+
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:
35+
36+
```
37+
signing.gnupg.executable=gpg
38+
signing.gnupg.useLegacyGpg=true
39+
signing.gnupg.homeDir=$e.g."~/.gnupg"
40+
signing.gnupg.keyName=$yourKeyName
41+
signing.password=$keysPassphrase
42+
# 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
51+
```
52+
53+
## Publish `master-SNAPSHOT` builds
54+
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.
56+
57+
The process is equal to the making of a release candidate, but without making any tags:
58+
59+
1. build and upload the `master-SNAPSHOT`:
60+
```
61+
git pull; git checkout master;
62+
```
63+
1. proceed as described in [Release candidate - Upload to Sonatype](https://github.com/metafacture/metafacture-core/wiki/Maintainer-Guidelines#upload-to-sonatype)
64+
65+
## Release candidate
66+
67+
*Release candidates should be tested by different people before releasing!*
68+
69+
### Prepare your release candidate
70+
71+
1. Make an rc-branch (necessary for Gradle to pick up the proper name):
72+
```
73+
git checkout -b A.B.C-rcN
74+
```
75+
(leave out the ` metafacture-core-` to avoid later the git "error: src refspec ... matches more than one" when you push the annotated git tag for having a tag named the same as the branch is not possible)
76+
1. Optionally, you can now test the build locally by invoking a Gradle target:
77+
```
78+
./gradlew assemble
79+
```
80+
81+
### Upload to Sonatype
82+
83+
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!):
84+
```
85+
./gradlew clean; ./gradlew publishToMavenLocal; ./gradlew publishToSonatype
86+
```
87+
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/).
88+
1. Make an annotated signed tag (it's important to do that _after_ uploading to Sonatype's snapshot repository because otherwise the `-SNAPSHOT` will not be appended to the release candidate thus will not land in `snapshot repository`):
89+
```
90+
git tag -s metafacture-core-A.B.C-rcN
91+
```
92+
1. Push the annotated signed tag to GitHub:
93+
```
94+
git push origin tag metafacture-core-A.B.C-rcN
95+
```
96+
97+
### Publish to [GitHub Packages](https://github.com/orgs/metafacture/packages?repo_name=metafacture-core)
98+
99+
1. Push your properly named branch to GitHub. Notice the `-rc` part of the branch's name:
100+
```
101+
git push origin A.B.C-rcN
102+
```
103+
Because there is `fetch --no-tags` in `actions/checkout@v2` the `-SNAPSHOT` suffix will always be appended (in comparison to doing `./gradlew publishAllPublicationsToGitHubPackagesRepository` locally, which will find the `SCM tag`). The publishing to GitHub packages is triggered then.
104+
105+
If we don't want `-SNAPSHOT` we may want to remove the `-SNAPSHOT` in `build.gradle`:
106+
```
107+
if (grgit.branch.current().name.contains('-rc')) { ...
108+
return "${grgit.branch.current().name}-SNAPSHOT"
109+
}
110+
```
111+
112+
Note that `Packages` is not the same as [`Releases`](https://github.com/metafacture/metafacture-core/releases).
113+
114+
### Consume the SNAPSHOT
115+
116+
1. See e.g. [Example for 5.5.1-rc1-SNAPSHOT](https://oss.sonatype.org/index.html#nexus-search;gav~org.metafacture~~5.5.1*~~) how to configure the dependency.
117+
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).
118+
For Maven update your `pom.xml` (after `</dependencies>`):
119+
```xml
120+
<repositories>
121+
<repository>
122+
<id>oss.sonatype.org-snapshot</id>
123+
<url>https://oss.sonatype.org/content/repositories/snapshots</url>
124+
<releases>
125+
<enabled>false</enabled>
126+
</releases>
127+
<snapshots>
128+
<enabled>true</enabled>
129+
</snapshots>
130+
</repository>
131+
</repositories>
132+
```
133+
For Gradle, add the snapshots repository:
134+
```gradle
135+
repositories {
136+
maven { url 'https://oss.sonatype.org/content/repositories/snapshots' }
137+
}
138+
```
139+
For Leiningen, add this to your `project.clj` (and be aware of the proper indentation!):
140+
```clojure
141+
:repositories [["snapshots" "https://oss.sonatype.org/content/repositories/snapshots"]]
142+
```
143+
For sbt, add this to your `build.sbt`:
144+
```
145+
resolvers += "Sonatype OSS Snapshots" at "https://oss.sonatype.org/content/repositories/snapshots"
146+
```
147+
148+
## Making a release
149+
150+
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.
151+
152+
1. Switch to `master` branch. Merge the approved `rc` into master:
153+
```
154+
git switch master; pull --no-ff origin A.B.C-rcN; git push origin master
155+
```
156+
157+
1. Make sure you have a signed tag locally:
158+
```
159+
git show metafacture-core-A.B.C
160+
```
161+
If it doesn't exist yet, create it:
162+
```
163+
git tag -s metafacture-core-A.B.C
164+
```
165+
1. When prompted, add a sensible commit message. For instance, something like:
166+
```
167+
Release 5.7.0
168+
```
169+
1. Make sure you have that signed tag pushed to GitHub:
170+
```
171+
git ls-remote --tags origin
172+
```
173+
If it is missing, push it with:
174+
```
175+
git push origin metafacture-core-A.B.C
176+
```
177+
1. Now the tag is available at 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:
178+
```
179+
./gradlew metafacture-runner:signArchive
180+
```
181+
and can be found in `metafacture-core/metafacture-runner/build/distributions/` (don't mind the `Source code` for that is created by GitHub automatically).
182+
1. Make sure to have a *clean* Git directory (otherwise only a SNAPSHOT will be built):
183+
```
184+
git status
185+
```
186+
1. Let the release be built and uploaded (the SCM tag will be detected and the release be built):
187+
```
188+
./gradlew clean; ./gradlew publishToMavenLocal; ./gradlew publishToSonatype
189+
```
190+
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 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.
191+

0 commit comments

Comments
 (0)