Here you will find all information about packaging, distributing or developing SimpleSAMLphp.

In order to release a new version of SimpleSAMLphp, please follow these steps:

1. Checkout the whole git repository.

% git clone https://github.com/simplesamlphp/simplesamlphp

or update an existing one:

% git fetch origin
% git pull origin master

2. If you are releasing a major version (e.g.: X.Y), then you need to create a new branch first:

% git checkout -b simplesamlphp-X.Y

Then push the new branch to the remote repository:

% git push -u origin simplesamlphp-X.Y

Remember to add a new upgrade notes document for the new branch if needed, and refer to it in the docs/index.md document.

If you are releasing a minor version (e.g.: X.Y.Z), then proceed to the next step directly.

3. Make sure you are in the appropriate branch corresponding to the latest major version:

% git checkout simplesamlphp-X.Y
% git pull origin simplesamlphp-X.Y

4a. One edit performs changes to the simplesamlphp-changelog.md in both master and the branch you are intending to release from

Update the release date in docs/simplesamlphp-changelog.md in the master branch and in the appropriate branch corresponding with this major version.

The below work flow updates the changelog for the feature branch first, then ports those updates to master, and then returns to the feature branch for the next step in the release.

% git checkout simplesamlphp-X.Y
% git pull origin simplesamlphp-X.Y
% editor docs/simplesamlphp-changelog.md
## copy updates here to clipboard.
% git add docs/simplesamlphp-changelog.md
% git commit -m "update changelog"

% git checkout master
% editor docs/simplesamlphp-changelog.md
## either cherry-pick the update from above or
## paste updates here and integrate them into the changelog.
% git add docs/simplesamlphp-changelog.md
% git commit -m "update changelog"

% git checkout simplesamlphp-X.Y
% git pull origin simplesamlphp-X.Y

4b. Write the version in the code. Edit the src/SimpleSAML/Configuration.php file and set the new version number:

% vim src/SimpleSAML/Configuration.php

    /**
     * The release version of this package
     */
    public const VERSION = 'X.Y.Z';

Please note this version number should be something like 0.0.x for major versions. Since you will create a branch for new major versions, and immediately after the first minor version, then you can directly set the version you are going to release (e.g.: 1.2.3 or 1.2.0-rc1 for release candidates).

Do the same for:

• The RPM specfile in extra/simplesamlphp.spec.

Set the version in the composer.json file: % composer config version vX.Y.Z

A composer update run should not be needed here. The composer.lock should already be updated.

5. Now you have to commit the change and push it to the repository:

% git add composer.json composer.lock docs/simplesamlphp-changelog.md extra/simplesamlphp.spec src/SimpleSAML/Configuration.php
% git status

% git commit -m "Setting version number to X.Y"
% git push origin

At this stage you should cool your heels and make sure that the CI system is happy with the push. Just in case something in composer is not happy for example you want to avoid making tags until it is all green from CI.

6. Create a new tag with the version number, named vX.Y.Z. If you are releasing a pre-release, use v.X.Y.0-rcN. To create a new stable release from the latest stable version (the branch you just checked out), not the master.

% git tag -s -a vX.Y.Z -m 'Releasing version X.Y.Z'

Note the -s flag in the command. It is used to sign the tag with PGP, which is useful for others to verify it was you who made this release. You will need PGP (or GnuPG) properly configured to sign the tag.

After you are done, make sure you push the tag to the repository:

% git push origin vX.Y.Z

If this is a pre-release, remember to use the vX.Y.0-rcN syntax for the version number.

7. If this is a new major version (i.e. x.y.0, the first of a new x.y series) update mk_docs.py in the simplesamlphp/docs repo to add this new version in the list of versions for which docs are built on the website. After pushing it the website will be updated automatically.

8. Now you are ready to build a new release. This is done automatically by pushing the tag:

% git push --tags

This will leave zip containing the tar.gz packages in Github Actions and prints a SHA256 hash to the screen in the last step of the workflow.

10. Upload the package to github. Go to the project page and proceed to releases. There you can edit releases associated with tags. Edit the tag you just created, give it a proper name and description as with the other releases there, including the digest (remember to follow the SHA256 checksum: `digest` format), and attach the package. The website will be updated automatically.

11. Visit the github actions page for simplesamlphp.github.io and refresh the docs to make sure the latest release is shown on the main and download pages. Trigger the workflow here.

12. Verify: Step 11 should have updated the changelog on the website. This can be verified by looking at the site adjusting the major version information for the one you just released. If the docs/X.Y changelog file has not been updated by step 11 then you can trigger a rebuild of that with the workflow here.

13. Make an announcement to the simplesamlphp and simplesamlphp-announce mailing lists.