Preparing a release

DEVELOPER DOCUMENTATION > RELEASE

Prepare a release!

ElkArte uses the release system provided by github.

A few days before the release start a draft of the release announcement.
In order to have a formatted result in the news section of the admin panel, remember to use HTML in the text of the release announcement.
As of 1.1.10 you can also use basic MD (headers, list, strong) in the announcement and it will present as formatted in the admin pane.
There are basically two kind of releases:

• minor and major releases with two attachments (a zip with the install package and one with an upgrade),
• micro releases with two attachments (a zip with the install package and one with a patch for the micro update)

This checklist is intended to be used as a template for the preparation of any release.

Before the release

• Do a fresh clone of the repository
• Verify that bootstrap.php has the correct FORUM_VERSION and CACHE_STALE.
• Verify that installcore.php has the correct CURRENT_VERSION.
• Generate detailed-version.js:
  • run generate_detailed-version.php from the root directory of the current patch version, the file can be found in the release_tools directory. This will validate that any changed files in the patch have correct/updated version headers. Be sure to do a full fetch and checkout of the patch branch.
    • specify b=[patch branch to compare against main] and v=[version level of patch] generate_detailed-version.php?b=patch_1-1-9&v=1.1.9
  • move the newly generated detailed-version.js out of the package directory
  • delete generate_detailed-version.php
  • note: generate_detailed-version.php will check that all the files changed during the preparation of the patch have the correct version number. The following git command is used by the script to obtain the list of files changed between two branches:

git log --name-only --pretty=oneline --full-index master..patch_1-0-x | grep -vE '^[0-9a-f]{40} ' | sort | uniq

• Commit detailed-version.js to gh-pages:
  • checkout the gh-pages branch (fetch the repository if necessary)
  • create a new branch
  • replace the file detailed-version.js with the one just generated
  • commit the changes
  • push online and send a PR to the ElkArte repository
• Create a pull request from the release branch (e.g. patch_1-0-x) to the master branch
• Write a draft of the release announcement. It should consist of:
  • a general description of the release
  • a release notes document including the major changes since the previous version (for development versions like alpha, beta and RC is the previous dev version, for final versions is the previous stable version).
  • a known issues document listing the major issues affecting the release (i.e. bugs not critical enough to be blocker, but potentially annoying)

The following command helps writing the list of changes used in the release notes:

git log --pretty=format:'[*][bugfix] %s ([url=https://github.com/elkarte/Elkarte/commit/%h]ref[/url]).' --abbrev-commit

Packages creation check list:

• From the root directory, run the release_tools/build.sh (e.g. bash release_tools/build.sh patch_1-1-9 1.1 9)
• The above command will clone the current ElkArte repo to subdirectory, change to the specified branch, remove extraneous files and generate a zip install file. In this example ElkArte_v1-1-9_install.zip

Patch creation check list:

• Fetch the latest version of patch_to_mod.php from the ElkArte Tools repository and place it in your forum root directory.
• Modify the $ignore_during_install variable as required for the release. This allows you to skip files and directories.
• Generate a diff between the current release branch and the new patch branch for example git diff --stat -p ElkArte/master..ElkArte/patch_1-1-9
• Point your browser to the patch_to_mod.php file and fill in the fields, use the output from the above command as the git diff file.
• The Patch file will be created in the packages directory.

Complete the release

• Merge the pull request for the detailed-version.js update
• Merge the pull request from the patch branch to the master branch
• Create a new release at github using the announcement previously drafted, and attach the packed files
• ...
• Profit!!!