-
Notifications
You must be signed in to change notification settings - Fork 130
Release process of a new stable release
This page outlines the steps required to generate a new release. Each step is defined below in detail. Creating a new stable release has the following steps:
- Run Perltidy on Code Base
- Merge the master branch into the stable branch
- Test until most are reasonably satisfied
- Tag the release in the stable branch
- Update the change log
- Regenerate and push user documentation to SourceForge
- Push a new zip file to SourceForge
- Announce the new release
Run perltidy on the entire code base to fix any improperly formatted contributions. This can be done by running the following command:
<path to mh>/bin/perltidyall
The command needs to be run twice as certain formatting changes require two runs to be fixed.
A while ago on the mailing list we (kind of) agreed to use the following branch structure in the MisterHouse repository:
- master branch is the branch where we actively develop code on
- stable branch is the branch that contains stable releases for normal users
New development takes place on master until the developers decide it is time for a new stable release. At that point we merge the current master branch into the stable branch, ask developers and users to test the stable branch, and once we have rough consensus we create a new release that we deploy into the stable branch.
Up to now Lieven Hollevoet has created the stable releases but in fact everybody who had write access to the main MisterHouse repository can create a new stable release.
NOTE: The steps here assume you have write access to the repository and have already setup a clone of hollie/misterhouse. If you are unsure of how to do this then first read up the docs and lets then talk about it on the mail list.
To create and publish a new stable release go through the following steps:
git pull
git checkout stable
git merge master
This ensures your local clone is up to date with hollie/misterhouse, changes the working copy to stable and then merges all changes that were applied from master into stable.
Update the version numbers in the user documentation docs/download.pod. This may not be necessary in the future once Issue #336 has been resolved.
Then, update the version number in the VERSION file and finally commit the updates:
git stage VERSION docs/download.pod
git commit -m "Upped version to v3.0"
git push origin stable
NOTE: The string in the VERSION file must be in the format <major>.<minor>, no more or less, to support automated version checking in the MisterHouse interface. Note there is NO leading "v".
The stable.zip link on the GitHub page will automatically be updated to the latest stable. Now it is time to ask others to test the new stable version. This process should be repeated from the top until all intended defects have been corrected. It might be worth while to use rc99 in the version string (i.e. v3.1-rc1) until ready to tag the release.
Once all of the desired defects have been corrected and any user documentation updates are complete, it is time to finalize the release. This starts by tagging release.
git tag -a v3.0 -m "New stable release version 3.0"
git push origin v3.0
NOTE: The tag must be in the format v<major>.<minor>, no more or less, to support automated version checking in the MisterHouse interface. Note the leading "v".
The stable.zip link on the GitHub page will automatically be updated to the latest stable, and the releases page will automatically list the current and the previous versions for later reference.
Update the changelog page for the new release and add a placeholder for adding new info for the upcoming release. Ideally the Changelog will be updated as development occurs, however, it is possible to review the closed tickets and pull requests to generate the Changelog entries. Using github_changelog_generator -u hollie -p misterhouse makes creating the changelog simpler.
First make sure that any required user documentation changes were made as part of the defect corrections for the release in the steps above. The MisterHouse user documentation is stored in .pod and .html files in the source tree docs/ directory. The process for making changes to these documentation files is the same as for any other source code change. You should checkout Maintaining MisterHouse Documentation for guidance.
Regenerating the documentation involves running the bin/update_docs script to create .html files from all the .pod files and from POD comments in the source code. I recommend that this be performed in a freshly cloned repository to make it simple since the script will generate a lot of files that should not be checked back into the repository. Another option is to git reset --hard HEAD when done transferring the files to SourceForge.
- Update local Git repository
cd { where your MH git clone lives }
git checkout master
git pull origin (or upstream)
- Generate the HTML from .pod where needed
cd docs
../bin/update_docs (ignore the complaint about html_alias_docs)
- Use SCP to copy the files to html.sourceforge.net
scp -p *.html *.css *.gif *.txt {yourusername}@web.sourceforge.net:/home/project-web/misterhouse/htdocs
scp -p lib/*.html {yourusername}@web.sourceforge.net:/home/project-web/misterhouse/htdocs/lib
- Undo the changes to your local repository
git reset --hard HEAD
git status
The web site hosting the user documentation is currently misterhouse.sourceforge.net. This site can only be updated by individuals that have been given specific permissions to update the files. It is important that the files on SourceForge are only updated using this method. If the SourceForge files are updated directly, the next release may overwrite the changes.
This step requires administrative access to the SourceForge site. Anyone wishing to take on the role of release manager is welcome to request administrator permissions on the mail list.
- Pull the zip and tar balls to your local system
Replace {version} with the version tag minus the leading v (e.g. 3.0)
wget --no-check-certificate -O misterhouse_v{version}.zip https://github.com/gitapi/repos/hollie/misterhouse/zipball/v{version}
wget --no-check-certificate -O misterhouse_v{version}.tar.gz https://github.com/gitapi/repos/hollie/misterhouse/tarball/v{version}
or
curl -k -o misterhouse_v{version}.zip https://codeload.github.com/hollie/misterhouse/legacy.zip/v{version}
curl -k -o misterhouse_v{version}.tar.gz https://codeload.github.com/hollie/misterhouse/legacy.tar.gz/v{version}
- Push them to SourceForge
Replace {version} with the version tag minus the leading v (e.g. 3.0)
Replace {your SF user name} with your username on SourceForge. You must have admin rights.
ssh {your SF user name},misterhouse@shell.sourceforge.net create
ssh {your SF user name},misterhouse@shell.sourceforge.net "mkdir -p /home/frs/project/misterhouse/misterhouse/{version}"
scp misterhouse_v{version}.tar.gz {your SF user name},misterhouse@web.sourceforge.net:/home/frs/project/misterhouse/misterhouse/{version}
scp misterhouse_v{version}.zip {your SF user name},misterhouse@web.sourceforge.net:/home/frs/project/misterhouse/misterhouse/{version}
scp -p README.md {your SF user name},misterhouse@web.sourceforge.net:/home/frs/project/misterhouse
OR..
Navigate to https://sourceforge.net/projects/misterhouse/files/misterhouse/ and there create a folder named <version_number> (e.g. '3.0') by clicking [create folder]. Enter that folder and upload the files you downloaded in the previous step by clicking the [add file] button.
Send a message to both the MisterHouse Users and MisterHouse Announce mailing lists. Only authorized senders can post a message to the MisterHouse Announce list, currently the list of authorized senders includes all user with GitHub write access. However, these senders may still need to log into the mailing list control panel to approve their message.