Skip to content

Latest commit

 

History

History
130 lines (94 loc) · 4.76 KB

RELEASE_HOWTO.md

File metadata and controls

130 lines (94 loc) · 4.76 KB
Raw

How to produce a xml-dtd release

Please follow these steps to produce a new release of xml-dtd.

Requirements

  • The Git version control system is required to obtain the sources. Any recent version should suffice.

  • Java 11 or later. You can install it from your favourite package manager or by downloading from Adoptium.

  • The generate_directory_index_caddystyle.py script and a recent version of Python (required to run it). The script is necessary to create the index files in the bare-bones Maven repository currently used by xml-dtd.

Steps

  1. If your local copy of the xml-dtd Git repository exactly matches the current master HEAD, use that copy to execute the gradlew commands shown later, otherwise create a new clone of the git@github.com:css4j/xml-dtd.git repository with git clone and use it.

For reference, let your copy of the xml-dtd release code be at /path/to/xml-dtd.

  1. Use changes.sh <new-version> to create a CHANGES.txt file with the changes from the latest tag. For example if you are releasing 4.3.1:
cd /path/to/xml-dtd
./changes.sh 4.3.1

Edit the resulting CHANGES.txt as convenient, to use it as the basis for the detailed list of changes when you fill the RELEASE_NOTES.md and the new release in Github.

Complete the Release Notes and update the version in the Gradle example of README.md, also check whether the dependencies mentioned there are correct. Commit the changes.

  1. Bump the version in the build.gradle file or remove the -SNAPSHOT suffix as necessary. Commit and push all the changes to the Git repository.

  2. If there is an issue tracking the release, close it.

  3. To check that everything is fine, build the code:

cd /path/to/xml-dtd
./gradlew build

  1. Clone the git@github.com:css4j/css4j.github.io.git repository (which contains a bare-bones Maven repository) and let /path/to/css4j.github.io be its location.

  2. From your copy of the xml-dtd release code, write the new artifacts into the local copy of the bare-bones Maven repository with:

cd /path/to/xml-dtd
./gradlew publish -PmavenReleaseRepoUrl="file:///path/to/css4j.github.io/maven"
  1. Produce the necessary directory indexes in the local copy of the bare-bones Maven repository using generate_directory_index_caddystyle.py:
cd /path/to/css4j.github.io/maven/io/sf/carte
generate_directory_index_caddystyle.py -r xml-dtd

If the changes to the css4j.github.io repository look correct, commit them but do not push yet.

  1. Clone the css4j-dist repository and execute ./gradlew mergedJavadoc. Move the javadocs from build/docs/javadoc to /path/to/css4j.github.io/api/latest:
rm -fr /path/to/css4j.github.io/api/latest
mkdir /path/to/css4j.github.io/api/latest
mv /path/to/css4j-dist/build/docs/javadoc/* /path/to/css4j.github.io/api/latest

If the changes to the css4j.github.io repo look correct, commit them with a description like "Latest modular Javadocs after xml-dtd 4.3.1" and push.

Check whether the "Examples" CI triggered by that commit to the css4j.github.io repository completed successfully. A failure could mean that the jar file is not usable with Java 8, for example.

  1. Create a v<version> tag in the xml-dtd Git repository. For example:
cd /path/to/xml-dtd
git tag -s v4.3.1 -m "Release 4.3.1"
git push origin v4.3.1

or git tag -a instead of -s if you do not plan to sign the tag. But it is generally a good idea to sign a release tag.

Alternatively, you could create the new tag when drafting the Github release (next step).

  1. Draft a new Github release at https://github.com/css4j/xml-dtd/releases

Use the contents of the RELEASE_NOTES.md file to summarize the most important changes in the release description.

Add to the Github release the jar files from this release.

  1. Verify that the new Github packages were created successfully by the Gradle Package task.

  2. In your local copy of the css4j-dist repository, update the xml-dtd version number in the maven/install-css4j.sh script. Commit the change, push and look for the completion of that project's CI.

  3. If there is a Github milestone about this release, close it.