Skip to content

Commit 3838bf1

Browse files
committed
Updated RELEASE.md instructions. No version bump.
1 parent ee6cbb6 commit 3838bf1

File tree

1 file changed

+180
-40
lines changed

1 file changed

+180
-40
lines changed

README/RELEASE.md

Lines changed: 180 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -1,46 +1,186 @@
1-
# HTACG HTML Tidy
1+
HTML Tidy Release Process Single Point Lesson (SPL)
2+
===================================================
23

3-
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...
4+
Purpose
5+
-------
6+
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.
47

5-
This assumes the current `next` branch is version 5.7.XXX. See VERSION.md for chosen version scheme.
68

7-
## Release Process for 5.8.0
9+
Definition
10+
----------
11+
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.
12+
13+
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.
14+
15+
16+
Release Process Overview
17+
------------------------
18+
The release process consists largely of the following steps:
819

920
### Lead up:
1021

11-
- Create the next release milestone, 5.10, if not already done...
12-
- Decide on PR's to include, bumping version.txt, accordingly...
13-
- Decide on any show-stopper outstanding issues, and action...
14-
- Change milestone of all excluded this time issues to the next 5.10 milestone, or to indefinite...
15-
- Decide target date for release...
16-
17-
### The Release:
18-
19-
1. Update version.txt to 5.8.0, and date... commit
20-
2. Create branch, `$ git checkout -b release/5.8`
21-
3. Update README/vershist.log... perl script... commit
22-
4. Add `$ git tag 5.8.0`
23-
5. Publish `$ git push -u origin release/5.8 --tags`
24-
6. Generate release 5.8.0.html... perl script... copy to...
25-
7. Create Github release v5.8.0 - becomes [Latest Release](https://github.com/htacg/tidy-html5/releases)
26-
8. Other things?
27-
- Generate release binaries
28-
- Add [binaries](http://binaries.html-tidy.org/)
29-
- Add api [docs](http://api.html-tidy.org/#part_apiref)
30-
- Update web pages [html-tidy.org](http://www.html-tidy.org/)
31-
32-
### Post:
33-
34-
- Update `master` branch to `release`
35-
- Update `next` version.txt to 5.9.0, open for new fixes...
36-
- Add more binaries...
37-
38-
## Notes on `Release Process`:
39-
40-
This **HTACG HTML Tidy** `official` release process must be supplemented with distribution by others.
41-
42-
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...
43-
44-
See [Get Tidy](http://www.html-tidy.org/#homepage19700601get_tidy) - This page really needs expanding. There are some suggestions pending, and more feedback welcome...
45-
46-
; eof
22+
- Create the next release milestone on Github if not already done.
23+
- Decide on PR's to include in the release, bumping version.txt, accordingly.
24+
- Decide on any show-stopper outstanding issues, and action them.
25+
- Change milestone of all excluded-this-time issues to the next milestone, or to indefinite.
26+
- Decide target date for release.
27+
28+
### Release:
29+
30+
- Update the version number to the next release version, e.g., from 5.5.xx to 5.6.0.
31+
- Generate a change log.
32+
- Push this change to `next`.
33+
- Merge this branch to `master`.
34+
- Tag the release on `master`.
35+
- 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.
36+
- Generate the API documentation for `next`.
37+
- Generate the API documentation for `master`.
38+
- Update the https://api.html-tidy.org/ website with the new API documentation.
39+
- Update the https://www.html-tidy.org/ website with the new release version.
40+
- Update the https://binaries.html-tidy.org/ website.
41+
- Push all of the changes.
42+
- Build binaries.
43+
- Create a Github release per the Git tag created above.
44+
- Post the binaries in the release.
45+
46+
47+
Release Steps in Detail
48+
--------------------------
49+
50+
### Update the version number to the next release version
51+
52+
In the `next` branch, modify the `version.txt` file to the next release version, for example, 5.8.0, and set the date.
53+
54+
55+
### Generate a change log
56+
57+
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.
58+
59+
~~~
60+
gem install github_changelog_generator
61+
~~~
62+
63+
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).
64+
65+
Generate the change log like so:
66+
67+
~~~
68+
github_changelog_generator -u htacg -p tidy-html5 \
69+
--token [github_access_token] \
70+
--since-tag 5.6.0 \
71+
--usernames-as-github-logins \
72+
--future-release 5.8.0 \
73+
-o README/testlog.md
74+
~~~
75+
76+
**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.
77+
78+
79+
### Commit this change to `next`
80+
81+
~~~
82+
git add .
83+
git commit -m 'Releasing HTML Tidy 5.8.0'
84+
~~~
85+
86+
87+
### Merge this branch to `master`
88+
89+
~~~
90+
git checkout master
91+
git merge next
92+
~~~
93+
94+
95+
### Tag the release on `master`
96+
97+
~~~
98+
git tag -a 5.8.0 -m "HTML Tidy version 5.8.0"
99+
~~~
100+
101+
102+
### Update the version number of the `next` branch
103+
104+
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
105+
commit it to the repository.
106+
107+
### Generate the API documentation for `next`
108+
109+
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.
110+
111+
After building, `cd` to the correct directory and build the documentation:
112+
113+
~~~
114+
cd html-tidy.org.api/tidy-html5-doxygen
115+
./build_docs.sh
116+
~~~
117+
118+
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/`.
119+
120+
121+
### Generate the API documentation for `master`
122+
123+
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.
124+
125+
After building, `cd` to the correct directory and build the documentation:
126+
127+
~~~
128+
cd html-tidy.org.api/tidy-html5-doxygen
129+
./build_docs.sh
130+
~~~
131+
132+
Move the resulting directory and file into `html-tidy.org.api/tidy/` directly.
133+
134+
### Update the https://api.html-tidy.org/ website with the new API documentation
135+
136+
Check the copyright dates in `_includes/footer.md`.
137+
138+
~~~
139+
cd html-tidy.org.api/
140+
git add .
141+
git commit -m "Added API documentation for master and next."
142+
git push
143+
~~~
144+
145+
### Update the https://www.html-tidy.org/ website with the new release version
146+
147+
Check the copyright dates in `_includes/footer.md`.
148+
149+
Update `html-tidy.org/homepage/_posts/1970-01-01-htmltidy.md` for the current release version and release year.
150+
151+
~~~
152+
cd html-tidy.org/
153+
git add .
154+
git commit -m "Added API documentation for master and next."
155+
git push
156+
~~~
157+
158+
159+
### Push all of the changes
160+
161+
Back in `tidy-html5/`
162+
163+
~~~
164+
git checkout master
165+
git push
166+
git push origin <tag_name>
167+
git checkout next
168+
git push
169+
~~~
170+
171+
172+
### Build binaries
173+
174+
This is OS specific.
175+
176+
### Create a Github release per the Git tag created above
177+
178+
Do this on Github.
179+
180+
### Post the binaries in the release
181+
182+
Post the binaries here.
183+
184+
### Update the https://binaries.html-tidy.org/ website
185+
186+
Modify the files to point to the binaries in the Github releases.

0 commit comments

Comments
 (0)