Updated RELEASE.md instructions. No version bump.
This commit is contained in:
Jim Derry
parent
ee6cbb6f98
commit
3838bf1c06
|
|
@ -1,46 +1,186 @@
|
|||
# HTACG HTML Tidy
|
||||
HTML Tidy Release Process Single Point Lesson (SPL)
|
||||
===================================================
|
||||
|
||||
The **Release Process** is made up of many little steps. These have been documented before in issues like [394-1](https://github.com/htacg/tidy-html5/issues/394#issuecomment-206952915), and [394-2](https://github.com/htacg/tidy-html5/issues/394#issuecomment-207814834), and others, but this is to further **document** the process...
|
||||
Purpose
|
||||
-------
|
||||
This lesson documents how to release a new, officially released version of HTML Tidy. Following the steps in this SPL ensures consistency between releases and results in a predictable experience for the end users of HTML Tidy.
|
||||
|
||||
This assumes the current `next` branch is version 5.7.XXX. See VERSION.md for chosen version scheme.
|
||||
|
||||
## Release Process for 5.8.0
|
||||
Definition
|
||||
----------
|
||||
HTACG HTML Tidy is a library and console application, and the release process is intended to officially designate a point of stability, where "stability" is ABI and API stability. "Stability" is represented by an even minor version number, and "released" means the HTACG has published and made available an even minor version number version of HTML Tidy.
|
||||
|
||||
Due to the number of platforms and language bindings which have adopted HTML Tidy, we are highly dependent on package managers to track the latest release versions of HTML Tidy, and release it on these other platforms. We cannot maintain distributions and language bindings for your favorite operating system or language package manager.
|
||||
|
||||
|
||||
Release Process Overview
|
||||
------------------------
|
||||
The release process consists largely of the following steps:
|
||||
|
||||
### Lead up:
|
||||
|
||||
- Create the next release milestone, 5.10, if not already done...
|
||||
- Decide on PR's to include, bumping version.txt, accordingly...
|
||||
- Decide on any show-stopper outstanding issues, and action...
|
||||
- Change milestone of all excluded this time issues to the next 5.10 milestone, or to indefinite...
|
||||
- Decide target date for release...
|
||||
|
||||
### The Release:
|
||||
|
||||
1. Update version.txt to 5.8.0, and date... commit
|
||||
2. Create branch, `$ git checkout -b release/5.8`
|
||||
3. Update README/vershist.log... perl script... commit
|
||||
4. Add `$ git tag 5.8.0`
|
||||
5. Publish `$ git push -u origin release/5.8 --tags`
|
||||
6. Generate release 5.8.0.html... perl script... copy to...
|
||||
7. Create Github release v5.8.0 - becomes [Latest Release](https://github.com/htacg/tidy-html5/releases)
|
||||
8. Other things?
|
||||
- Generate release binaries
|
||||
- Add [binaries](http://binaries.html-tidy.org/)
|
||||
- Add api [docs](http://api.html-tidy.org/#part_apiref)
|
||||
- Update web pages [html-tidy.org](http://www.html-tidy.org/)
|
||||
- Create the next release milestone on Github if not already done.
|
||||
- Decide on PR's to include in the release, bumping version.txt, accordingly.
|
||||
- Decide on any show-stopper outstanding issues, and action them.
|
||||
- Change milestone of all excluded-this-time issues to the next milestone, or to indefinite.
|
||||
- Decide target date for release.
|
||||
|
||||
### Post:
|
||||
### Release:
|
||||
|
||||
- Update `master` branch to `release`
|
||||
- Update `next` version.txt to 5.9.0, open for new fixes...
|
||||
- Add more binaries...
|
||||
- Update the version number to the next release version, e.g., from 5.5.xx to 5.6.0.
|
||||
- Generate a change log.
|
||||
- Push this change to `next`.
|
||||
- Merge this branch to `master`.
|
||||
- Tag the release on `master`.
|
||||
- Update the version number of the `next` branch to the next development version, e.g., from 5.8.0 to 5.9.0. At this point, both versions are identical except for the version number.
|
||||
- Generate the API documentation for `next`.
|
||||
- Generate the API documentation for `master`.
|
||||
- Update the https://api.html-tidy.org/ website with the new API documentation.
|
||||
- Update the https://www.html-tidy.org/ website with the new release version.
|
||||
- Update the https://binaries.html-tidy.org/ website.
|
||||
- Push all of the changes.
|
||||
- Build binaries.
|
||||
- Create a Github release per the Git tag created above.
|
||||
- Post the binaries in the release.
|
||||
|
||||
## Notes on `Release Process`:
|
||||
|
||||
This **HTACG HTML Tidy** `official` release process must be supplemented with distribution by others.
|
||||
|
||||
Of course, if possible, we recomend building tidy from the git source, it is easy, but also in some OS'es others offer distribution in various ways...
|
||||
Release Steps in Detail
|
||||
--------------------------
|
||||
|
||||
See [Get Tidy](http://www.html-tidy.org/#homepage19700601get_tidy) - This page really needs expanding. There are some suggestions pending, and more feedback welcome...
|
||||
### Update the version number to the next release version
|
||||
|
||||
; eof
|
||||
In the `next` branch, modify the `version.txt` file to the next release version, for example, 5.8.0, and set the date.
|
||||
|
||||
|
||||
### Generate a change log
|
||||
|
||||
If necessary, install the `github_changelog_generator`. This requires that you have a Ruby environment on your computer, which you probably do because the regression tests require it.
|
||||
|
||||
~~~
|
||||
gem install github_changelog_generator
|
||||
~~~
|
||||
|
||||
You’ll also need a Github personal access token in order for the tool to pull information from Github. You can acquire one [here](https://github.com/settings/tokens).
|
||||
|
||||
Generate the change log like so:
|
||||
|
||||
~~~
|
||||
github_changelog_generator -u htacg -p tidy-html5 \
|
||||
--token [github_access_token] \
|
||||
--since-tag 5.6.0 \
|
||||
--usernames-as-github-logins \
|
||||
--future-release 5.8.0 \
|
||||
-o README/testlog.md
|
||||
~~~
|
||||
|
||||
**Important**: the `--since-tag` value should be the git tag of the previous release, because we're only interested in the changes since then. The `--future-release` value should be the git tag that you _will apply_ (but have not yet) for this release.
|
||||
|
||||
|
||||
### Commit this change to `next`
|
||||
|
||||
~~~
|
||||
git add .
|
||||
git commit -m 'Releasing HTML Tidy 5.8.0'
|
||||
~~~
|
||||
|
||||
|
||||
### Merge this branch to `master`
|
||||
|
||||
~~~
|
||||
git checkout master
|
||||
git merge next
|
||||
~~~
|
||||
|
||||
|
||||
### Tag the release on `master`
|
||||
|
||||
~~~
|
||||
git tag -a 5.8.0 -m "HTML Tidy version 5.8.0"
|
||||
~~~
|
||||
|
||||
|
||||
### Update the version number of the `next` branch
|
||||
|
||||
For example, from from 5.8.0 to 5.9.0. At this point, both versions are identical except for the version number. Edit the `version.txt` file to make this change, and then
|
||||
commit it to the repository.
|
||||
|
||||
### Generate the API documentation for `next`
|
||||
|
||||
First, build the `next` binary in `build/cmake`, so that API documentation tools have a correct version of HTML Tidy to work with. Perform a `git clean -xdf` in this directory prior to building for good measure.
|
||||
|
||||
After building, `cd` to the correct directory and build the documentation:
|
||||
|
||||
~~~
|
||||
cd html-tidy.org.api/tidy-html5-doxygen
|
||||
./build_docs.sh
|
||||
~~~
|
||||
|
||||
Then in the `html-tidy.org.api/tidy-html5-doxygen/output` directory, rename the resulting directory and file to `tidylib_api_next/` and `quickref_next.html`, and move them into `html-tidy.org.api/tidy/`.
|
||||
|
||||
|
||||
### Generate the API documentation for `master`
|
||||
|
||||
First, checkout `master` build the binary in `build/cmake`, so that API documentation tools have a correct version of HTML Tidy to work with. Perform a `git clean -xdf` in this directory prior to building for good measure.
|
||||
|
||||
After building, `cd` to the correct directory and build the documentation:
|
||||
|
||||
~~~
|
||||
cd html-tidy.org.api/tidy-html5-doxygen
|
||||
./build_docs.sh
|
||||
~~~
|
||||
|
||||
Move the resulting directory and file into `html-tidy.org.api/tidy/` directly.
|
||||
|
||||
### Update the https://api.html-tidy.org/ website with the new API documentation
|
||||
|
||||
Check the copyright dates in `_includes/footer.md`.
|
||||
|
||||
~~~
|
||||
cd html-tidy.org.api/
|
||||
git add .
|
||||
git commit -m "Added API documentation for master and next."
|
||||
git push
|
||||
~~~
|
||||
|
||||
### Update the https://www.html-tidy.org/ website with the new release version
|
||||
|
||||
Check the copyright dates in `_includes/footer.md`.
|
||||
|
||||
Update `html-tidy.org/homepage/_posts/1970-01-01-htmltidy.md` for the current release version and release year.
|
||||
|
||||
~~~
|
||||
cd html-tidy.org/
|
||||
git add .
|
||||
git commit -m "Added API documentation for master and next."
|
||||
git push
|
||||
~~~
|
||||
|
||||
|
||||
### Push all of the changes
|
||||
|
||||
Back in `tidy-html5/`
|
||||
|
||||
~~~
|
||||
git checkout master
|
||||
git push
|
||||
git push origin <tag_name>
|
||||
git checkout next
|
||||
git push
|
||||
~~~
|
||||
|
||||
|
||||
### Build binaries
|
||||
|
||||
This is OS specific.
|
||||
|
||||
### Create a Github release per the Git tag created above
|
||||
|
||||
Do this on Github.
|
||||
|
||||
### Post the binaries in the release
|
||||
|
||||
Post the binaries here.
|
||||
|
||||
### Update the https://binaries.html-tidy.org/ website
|
||||
|
||||
Modify the files to point to the binaries in the Github releases.
|
||||
|
|
|
|||
Loading…
Reference in a new issue