[doc] update versioning and release guide #3962

line-o · 2021-06-30T20:01:37Z

closes #3845
closes #3914
Follow-up on the last release the guide how-to release a new version of exist-db was reworked.

sonarqubecloud · 2021-06-30T20:26:39Z

Kudos, SonarCloud Quality Gate passed!

0 Bugs
0 Vulnerabilities
0 Security Hotspots
0 Code Smells

No Coverage information
No Duplication information

adamretter

Good start! Needs some expansion and reordering of tasks

adamretter · 2021-06-30T20:14:12Z

exist-versioning-release.md


 ## Release Process

-This section details concrete steps for creating and publishing product releases. Each section here assumes you are starting with a clean Git checkout of the `develop` branch from [https://github.com/eXist-db/exist.git](https://github.com/eXist-db/exist.git).


As discussed in the calls, I believe it is important to always start a release from a clean git checkout of the develop branch. So I think this section should not be removed

Yes, this is why we decided to make this a dedicated step. That way there is less chance to miss it.

Thanks, I see that below now, but I do think it is better at the beginning or at least also a note at the beginning.

adamretter · 2021-06-30T20:16:00Z

exist-versioning-release.md

+
+```
+gpg --list-secret-keys --keyid-format SHORT
+/Users/username/.gnupg/pubring.kbx


I think we need to be more generic here. On none of my machines are the files for GPG named like the ones here!

The above is sample output. That is also the more recent format as is layed out in a previous section.

adamretter · 2021-06-30T20:17:14Z

exist-versioning-release.md

+sec   rsa4096/12345678 2013-04-26 [SC]
+```
+
+This gives you the keystore you are using (here: `/Users/username/.gnupg/pubring.kbx`) and your key-id (here: `12345678` the part after rsa4096/). 


I think keystore is the wrong terminology here. keystore is used in the Java world. For GPG I believe the correct terminology is "public key ring"

agreed, my mistake, will fix it

adamretter · 2021-06-30T20:18:40Z

exist-versioning-release.md

+This gives you the keystore you are using (here: `/Users/username/.gnupg/pubring.kbx`) and your key-id (here: `12345678` the part after rsa4096/). 
+
+**Important Note** 
+GnuPG is using an [optimized keystore since version 2.1](https://www.gnupg.org/documentation/manuals/gnupg/GPG-Configuration.html) which contains public and secret keys. Former GnuPG version had seperated keystore for public (~/.gnupg/pubring.gpg) and private keys (~/.gnupg/secring.gpg). 


This should be moved before the commands (see comment above).

Agreed, once its above the sample I think the discussion which keyring we show in the sample is not so important anymore, or is it? Point is since GnuPG 2.1 is .kbx thats why I would vote for the .kbx sample but I don't have strong feeling about it.. @adamretter what is printed if you run the command, only the pubring.gpg or secring.gpg and pubring.gpg ?

adamretter · 2021-06-30T20:20:54Z

exist-versioning-release.md

+To test gpg simply create a file `test.txt` and run`gpg -ab test.txt`to sign it. you should see a new file `test.txt.asc` which means GnuPG signing worked fine. 
+
+##### Java KeyStore 
+* To create an eXist-db release a Java KeyStore with key is needed to sign the IzPack Installer. In case you don't have a Java KeyStore you can create one with: 


you can create one with - we should add some text, that it is important that the user realises this should be an exceptional circumstance and not the normal, because if they use a self-generated key, then there is no authenticity. Ideally the user should use a real key purchased from a code-signing vendor.

Yes, I agree that this should be added in greater detail.

adamretter · 2021-06-30T20:50:23Z

exist-versioning-release.md

+      -Pinstaller \
+      -Pconcurrency-stress-tests \
+      -Pmicro-benchmarks \
+      -Darguments="-Djarsigner.skip=false -Dmac-signing=true -Dmac.codesign.identity=\"your codesign ID\"" \


The -P args should likely be repeated in the -Dargument

Not needed. I spent Saturday night running this back and forth.

adamretter · 2021-06-30T20:51:16Z

exist-versioning-release.md

    ```
-    $ git push origin eXist-5.3.0:master
+
+    #### Notarizing macOSX installer (work in progress)


This seems to be in the wrong place. Also see my comments above about Notarization and where it needs to happen...

adamretter · 2021-06-30T20:54:20Z

exist-versioning-release.md

+    The notarized installer containing the notarized app must then be uploaded to the github releases page.
+
+    
+2. Update the stable branch (`master`) of eXist-db to reflect the latest release:


Before this... A visual checklist of things needs to be completed. Was the output of the release:perform step as expected. Do the new version numbers look correct locally? do they look correct on the exist-db GitHub? Does the tag look correct, did the tag get pushed to the exist-db GitHub? Has at least one other person also checked such things and also confirmed this to you?

Also before modifying master, I would suggest that the oss.sonatype.org artifacts have to be released successfully. Sonatype has its own suite of checks, and if the artifacts fail those for some reason, then you have to undo the release process, fix the issue, go all the way back to the start of the release process and start again. So it is important that Sonatatype artifacts are published OK before we change master. Changing master should really be the last thing that ever happens (apart from perhaps tweeting/emailing/etc)

Interesting. This sounds like very important information that belongs in this guide.

adamretter · 2021-06-30T20:56:31Z

exist-versioning-release.md

+    2.1. Warning: there is a known issue in AtomicWiki where your release notes might suddenly disappear. In case this happens your data is not lost but stored in `/db/apps/wiki/data/blogs/eXist/.md`. You can rename it or move the content to a `eXistdb<VERSION>.md` file and create an according `eXistdb<VERSION>.atom` for it. Once these two files are available the blog entry will become visible on the eXist-db homepage and it will be visible in the eXist-db blog. 

-7.  Visit the GitHub releases page [https://github.com/eXist-db/exist/releases](https://github.com/eXist-db/exist/releases) and create a new release, enter the tag you previously created and link the release notes from the blog.
+3.  Visit the GitHub releases page [https://github.com/eXist-db/exist/releases](https://github.com/eXist-db/exist/releases) and create a new release, enter the tag you previously created and link the release notes from the blog.


Does this still need to be done? doesn't the github-release-plugin now take care of some of this?

Good catch. Will be removed

adamretter · 2021-06-30T20:57:50Z

exist-versioning-release.md

+8. Update the Wikipedia page with the new version details - [https://en.wikipedia.org/wiki/EXist](https://en.wikipedia.org/wiki/EXist).

-13. Go to GitHub and move all issues and PRs which are still open for the release milestone to the next release milestone. Close the release milestone.
+9. Go to GitHub and move all issues and PRs which are still open for the release milestone to the next release milestone. Close the release milestone.


We need to expand on this as it caused confusion this time... if the release was a "patch" move the issues to the next logical "patch" milestone, likewise for "feature" and "minor" releases.

adamretter · 2021-06-30T21:19:03Z

exist-versioning-release.md

+    
+    ```bash
+    git checkout -b next-master eXist-5.3.0
+    git push origin next-master:master


You don't need the intermediate branch, you can push the tag (either local or remote) directly to the remote master,

I tried that and it did not work.

It might work but as it it also might fail I would prefer the safer option.

I tried that and it did not work.

Tried what? Unless you share the commands, and the error, I can't comment. All I can tell you is that is how it has been done for previous released...

It might work but as it it also might fail I would prefer the safer option.

Git is atomic, it will either succeed or fail, and it will always do so in a safe-way

git push origin eXist-5.3.0:master resulted in eXist-5.3.0 -> master(bad ref) on a fresh clone after building

joewiz · 2021-06-30T22:19:37Z

exist-versioning-release.md

+3.  Visit the GitHub releases page [https://github.com/eXist-db/exist/releases](https://github.com/eXist-db/exist/releases) and create a new release, enter the tag you previously created and link the release notes from the blog.

-8.  Send an email to the `exist-open` mailing list announcing the release with a title similar to `[ANN] Release of eXist 5.3.0`, copy and paste the release notes from the blog into the email and reformat appropriately (see past emails).
+4.  Send an email to the `exist-open` mailing list announcing the release with a title similar to `[ANN] Release of eXist 5.3.0`, copy and paste the release notes from the blog into the email and reformat appropriately (see [past emails](https://sourceforge.net/p/exist/mailman/search/?mail_list=exist-open)).


Could you add an item: "Send a note to the eXist-db.org Slack #community channel" with a link to the release notes? (Phew, that's a lot of outreach duties!)

Also, it would be nice if we could find some convenient way to email the rendered HTML of the release notes, rather than the raw markdown.

[doc] update versioning and release guide

ac57ac9

line-o mentioned this pull request Jun 30, 2021

Update Homebrew release notes #3952

Closed

adamretter self-requested a review June 30, 2021 20:13

adamretter suggested changes Jun 30, 2021

View reviewed changes

adamretter reviewed Jun 30, 2021

View reviewed changes

joewiz reviewed Jun 30, 2021

View reviewed changes

line-o mentioned this pull request Jul 1, 2021

[Master issue] Prepare eXist 5.3.0 stable release #3914

Closed

38 tasks

line-o added this to the eXist-5.3.1 milestone Jul 1, 2021

line-o mentioned this pull request Jul 2, 2021

Fix release process since migration from BinTray to GitHub Releases #3845

Open

2 tasks

joewiz mentioned this pull request Jul 5, 2021

[Master issue] Prepare 5.4.0 and/or 6.0.0 release #3968

Closed

18 tasks

adamretter modified the milestones: eXist-5.3.1, eXist-5.3.2 Dec 16, 2021

adamretter modified the milestones: eXist-5.3.2, eXist-6.0.2 Feb 14, 2022

line-o marked this pull request as draft October 17, 2022 17:43

adamretter modified the milestones: eXist-6.0.2, eXist-6.1.1 Jan 15, 2023

adamretter modified the milestones: eXist-6.1.1, eXist-7.0.1 Feb 4, 2023

duncdrum mentioned this pull request May 5, 2025

[fix] replace test SSL certificate #5725

Merged

line-o added this to v7.0.0 May 7, 2025


		## Release Process

		This section details concrete steps for creating and publishing product releases. Each section here assumes you are starting with a clean Git checkout of the `develop` branch from [https://github.com/eXist-db/exist.git](https://github.com/eXist-db/exist.git).

		The notarized installer containing the notarized app must then be uploaded to the github releases page.


		2. Update the stable branch (`master`) of eXist-db to reflect the latest release:

Uh oh!

[doc] update versioning and release guide #3962

Are you sure you want to change the base?

[doc] update versioning and release guide #3962

Uh oh!

Conversation

line-o commented Jun 30, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sonarqubecloud bot commented Jun 30, 2021

Uh oh!

adamretter left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

windauer Jun 30, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adamretter Jun 30, 2021 • edited by joewiz Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

line-o commented Jun 30, 2021 •

edited

Loading

windauer Jun 30, 2021 •

edited

Loading

adamretter Jun 30, 2021 •

edited by joewiz

Loading