Merge remote-tracking branch 'origin/657-rdf-marker-configurator' into 589-fixRunnerExamples

Author: TobiasNx

.gitignore

@@ -14,16 +14,15 @@
 # limitations under the License.
 #
 
-# Ignore temporary maven files:
-target/
-
 # Ignore temporary gradle files:
-.gradle/
-.gradletasknamecache
+/.gradle/
 build/
 
-# Ignore tmp directory
-tmp
+# Ignore temporary files:
+*.jfr
+generated/
+tmp/
+xtext-gen/
 
 # Ignore Eclipse project files:
 .checkstyle
@@ -38,30 +37,25 @@ tmp
 *.iws
 *.iml
 .idea
-/out/
-/*/out/
+out/
 
-# Ignore IntelliJ JIRA plugin
+# Ignore IntelliJ JIRA plugin:
 atlassian-ide-plugin.xml
 
-# Ignore files generated by CI:
-buildbot.keyring
-
-# Ignore VS code/codium config files
+# Ignore VS code/codium config files:
+*.vsix
 .vscode
 
-# Ignore files with sensitive data
+# Ignore files with sensitive data:
 gradle.properties
 secring.gpg
 
-# Ignore metafacture-fix files
-*.jfr
-*.vsix
-generated/
+# Ignore metafix-vsc files:
 node_modules/
 package-lock.json
-xtext-gen/
 xtext-server/
+
+# Ignore metafix integration test files:
 /metafix/src/test/resources/org/metafacture/metafix/integration/**/*.diff
 /metafix/src/test/resources/org/metafacture/metafix/integration/**/*.err
 /metafix/src/test/resources/org/metafacture/metafix/integration/**/*.out

CONTRIBUTING.md

@@ -173,4 +173,4 @@ The *Definition of Done* describes a list of criteria which issues have to meet
 
 ### Releasing Metafacture
 
-Follow the [wiki's Maintainer-Guidelines](https://github.com/metafacture/metafacture-core/wiki/Maintainer-Guidelines).
+Follow the [MAINTAINING.md](https://github.com/metafacture/metafacture-core/blob/master/MAINTAINING.md).

MAINTAINING.md

@@ -0,0 +1,191 @@
+# Merging pull requests
+
+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.
+For example, to merge a pull request `fix-xy` from http://github.com/cboehme/metafacture-core the following Git commands should be used:
+```
+# Bring master up-to-date:
+git checkout master
+git fetch
+git rebase
+# Fetch pull request:
+git fetch http://github.com/cboehme/metafacture-core.git +fix-xy:cboehme-fix-xy
+git checkout cboehme-fix-xy
+# Merge master:
+git merge master
+# Run test cases, check commit, add fixup commits ...
+# Merge into master
+git checkout master
+git merge --no-ff cboehme-fix-xy
+```
+The commit message of the merge command should follow this format:
+```
+Merge pull-request #PULLREQUEST-ID from cboehme/fix-xy
+```
+
+# Releasing
+
+We shall make releases quarterly. Approximate timetable is every Januar, April, July, October.
+We may publish `master-SNAPSHOT` builds more frequently.
+
+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.
+
+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`).
+
+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:
+
+```
+signing.gnupg.executable=gpg
+signing.gnupg.useLegacyGpg=true
+signing.gnupg.homeDir=$e.g."~/.gnupg"
+signing.gnupg.keyName=$yourKeyName
+signing.password=$keysPassphrase
+# depending on gradle plugin versions etc. you may need to use:
+# signing.keyId=$yourKeyName
+# signing.secretKeyRingFile=$e.g."~/.gnupg/secring.gpg"
+#  Go to https://s01.oss.sonatype.org/
+#  Go to profile
+#  Change the pulldown from “Summary” to “User Token”
+#  Click on “Access User Token”
+sonatypeUsername=$usernameOfAccessUserToken
+sonatypePassword=$token
+```
+
+## Publish `master-SNAPSHOT` builds
+
+These are done more often, in irregular intervals. They are not considered stable and may break your application, so be cautious when using them.
+
+The process is equal to the making of a release candidate, but without making any tags:
+
+1. build and upload the `master-SNAPSHOT`:
+    ```
+    git pull; git checkout master;
+    ```
+1. proceed as described in [Release candidate - Upload to Sonatype](https://github.com/metafacture/metafacture-core/wiki/Maintainer-Guidelines#upload-to-sonatype)
+
+## Release candidate
+
+*Release candidates should be tested by different people before releasing!*
+
+### Prepare your release candidate
+
+1. Make an rc-branch (necessary for Gradle to pick up the proper name):
+    ```
+    git checkout -b A.B.C-rcN
+    ```
+    (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)
+1. Optionally, you can now test the build locally by invoking a Gradle target:
+    ```
+    ./gradlew assemble
+    ```
+
+### Upload to Sonatype
+
+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!):
+    ```
+    ./gradlew clean; ./gradlew publishToMavenLocal; ./gradlew publishToSonatype
+    ```
+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/).
+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`):
+    ```
+    git tag -s metafacture-core-A.B.C-rcN
+    ```
+1. Push the annotated signed tag to GitHub:
+    ```
+    git push origin tag metafacture-core-A.B.C-rcN
+    ```
+
+### Publish to [GitHub Packages](https://github.com/orgs/metafacture/packages?repo_name=metafacture-core)
+
+1. Push your properly named branch to GitHub. Notice the `-rc` part of the branch's name:
+    ```
+    git push origin A.B.C-rcN
+    ```
+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.
+
+If we don't want `-SNAPSHOT` we may want to remove the `-SNAPSHOT` in `build.gradle`:
+```
+if (grgit.branch.current().name.contains('-rc')) { ...
+    return "${grgit.branch.current().name}-SNAPSHOT"
+}
+```
+
+Note that `Packages` is not the same as [`Releases`](https://github.com/metafacture/metafacture-core/releases).
+
+### Consume the SNAPSHOT
+
+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.
+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).
+    For Maven update your `pom.xml` (after `</dependencies>`):
+    ```xml
+    <repositories>
+        <repository>
+            <id>oss.sonatype.org-snapshot</id>
+            <url>https://oss.sonatype.org/content/repositories/snapshots</url>
+            <releases>
+                <enabled>false</enabled>
+            </releases>
+            <snapshots>
+                <enabled>true</enabled>
+            </snapshots>
+        </repository>
+    </repositories>
+    ```
+    For Gradle, add the snapshots repository:
+    ```gradle
+    repositories {
+        maven { url 'https://oss.sonatype.org/content/repositories/snapshots' }
+    }
+    ```
+    For Leiningen, add this to your `project.clj` (and be aware of the proper indentation!):
+    ```clojure
+        :repositories [["snapshots" "https://oss.sonatype.org/content/repositories/snapshots"]]
+    ```
+    For sbt, add this to your `build.sbt`:
+    ```
+    resolvers += "Sonatype OSS Snapshots" at "https://oss.sonatype.org/content/repositories/snapshots"
+    ```
+
+## Making a release
+
+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.
+
+1. Switch to `master` branch. Merge the approved `rc` into master:
+    ```
+    git switch master; pull --no-ff origin A.B.C-rcN; git push origin master
+    ```
+
+1. Make sure you have a signed tag locally:
+    ```
+    git show metafacture-core-A.B.C
+    ```
+    If it doesn't exist yet, create it:
+    ```
+    git tag -s metafacture-core-A.B.C
+    ```
+1. When prompted, add a sensible commit message. For instance, something like:
+    ```
+    Release 5.7.0
+    ```
+1. Make sure you have that signed tag pushed to GitHub:
+    ```
+    git ls-remote --tags origin
+    ```
+    If it is missing, push it with:
+    ```
+    git push origin  metafacture-core-A.B.C
+    ```
+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:
+    ```
+    ./gradlew metafacture-runner:signArchive
+    ```
+    and can be found in `metafacture-core/metafacture-runner/build/distributions/` (don't mind the `Source code` for that is created by GitHub automatically).
+1. Make sure to have a *clean* Git directory (otherwise only a SNAPSHOT will be built):
+    ```
+    git status
+    ```
+1. Let the release be built and uploaded (the SCM tag will be detected and the release be built):
+    ```
+    ./gradlew clean; ./gradlew publishToMavenLocal; ./gradlew publishToSonatype
+    ```
+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.
+

build.gradle

@@ -165,8 +165,7 @@ subprojects {
   }
 
   checkstyle {
-    toolVersion '8.30'
-    checkstyleTest.enabled = false
+    toolVersion '10.21.2'
   }
 
   test {

config/checkstyle/checkstyle.xml

@@ -86,7 +86,9 @@
         <module name="MagicNumber"/>
         <module name="MemberName"/>
         <module name="MethodLength"/>
-        <module name="MethodName"/>
+        <module name="MethodName">
+            <property name="format" value="^(?:issue[0-9]+_)*[a-z][a-zA-Z0-9]*$"/>
+        </module>
         <module name="MethodParamPad"/>
         <module name="MethodTypeParameterName"/>
         <module name="MissingCtor"/>
@@ -148,7 +150,7 @@
         <module name="SimplifyBooleanReturn"/>
         <module name="StaticVariableName">
             <!-- disallow static, non-final variables -->
-            <!--<property name="format" value="^$"/>-->
+            <property name="format" value="^$"/>
         </module>
         <module name="StringLiteralEquality"/>
         <module name="SuperClone"/>

metafacture-biblio/src/main/java/org/metafacture/biblio/pica/PicaEncoder.java

@@ -62,7 +62,7 @@ public final class PicaEncoder extends DefaultStreamPipe<ObjectReceiver<String>>
     private static final String FIELD_NAME_PATTERN_STRING = "\\d{3}.(/..)?";
     private static final Pattern FIELD_NAME_PATTERN = Pattern.compile(FIELD_NAME_PATTERN_STRING);
 
-    private static StringBuilder builder = new StringBuilder(); //Result of the encoding process
+    private static final StringBuilder BUILDER = new StringBuilder(); // Result of the encoding process
 
     private boolean entityOpen; // Flag to inform whether an entity is opened.
     private boolean idnControlSubField; // Flag to inform whether it is the 003@ field.
@@ -80,7 +80,7 @@ public PicaEncoder() {
     public void startRecord(final String recordId) {
         // the name is a idn, which should be found in the encoded data under 003@.
         //any rest of the previous record is cleared before the new begins.
-        builder.setLength(0);
+        BUILDER.setLength(0);
         this.id = recordId;
         //Now an entity can be opened. But no literal is allowed.
         this.entityOpen = false;
@@ -118,7 +118,7 @@ public void startEntity(final String name) {
         if (entityOpen) { //No nested entities are allowed in pica+.
             throw new FormatException(name);
         }
-        builder.append(name.trim() + " ");
+        BUILDER.append(name.trim() + " ");
 
         idnControlSubField = !ignoreRecordId && FIELD_IDN_INTERN.equals(name.trim());
         //Now literals can be opened but no more entities.
@@ -142,28 +142,28 @@ public void literal(final String name, final String value) {
             }
             idnControlSubField = false; //only one record ID will be checked.
         }
-        builder.append(SUB_DELIMITER);
-        builder.append(name);
-        builder.append(valueNew);
+        BUILDER.append(SUB_DELIMITER);
+        BUILDER.append(name);
+        BUILDER.append(valueNew);
     }
 
     @Override
     public void endEntity() {
-        builder.append(FIELD_DELIMITER);
+        BUILDER.append(FIELD_DELIMITER);
         //Now an entity can be opened. But no literal is allowed.
         this.entityOpen = false;
     }
 
     @Override
     public void endRecord() {
-        getReceiver().process(builder.toString());
+        getReceiver().process(BUILDER.toString());
         //No literal is allowed.
         this.entityOpen = false;
     }
 
     @Override
     protected void onResetStream() {
-        builder.setLength(0);
+        BUILDER.setLength(0);
     }
 
 }

metafacture-biblio/src/test/java/org/metafacture/biblio/AlephMabXmlHandlerTest.java

@@ -16,10 +16,11 @@
 
 package org.metafacture.biblio;
 
+import org.metafacture.framework.StreamReceiver;
+
 import org.junit.Before;
 import org.junit.Rule;
 import org.junit.Test;
-import org.metafacture.framework.StreamReceiver;
 import org.mockito.InOrder;
 import org.mockito.Mock;
 import org.mockito.Mockito;
@@ -44,6 +45,9 @@ public final class AlephMabXmlHandlerTest {
 
     private AlephMabXmlHandler mabXmlHandler;
 
+    public AlephMabXmlHandlerTest() {
+    }
+
     @Before
     public void setup() {
         mabXmlHandler = new AlephMabXmlHandler();