about summary refs log tree commit diff
path: root/Etc/creating-a-release.txt
blob: 16784a0548e1a3816561ff05c7d210e6c7d7e874 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
To create a zsh release:

- Be satisfied that 'master' is releaseable.
  (No recent destabilizing changes, `make check` passes, etc)

- Bump or update:

	Config/version.mk to today's date
	Config/version.mk version number
	Etc/FAQ.yo
	README
	NEWS

  The version-number sequence is as follows:

	5.8, 5.8.0.1-dev, 5.8.0.2-test, 5.8.1, 5.8.1.1-dev, 5.8.1.2-test, 5.9

  Please note:

	- All version numbers in this document are examples only and may not
	  reflect the actual version history of the shell.
	- A slightly different ordering of version-number components was used
	  prior to zsh 5.8. All subsequent releases should use the scheme
	  described above.
	- Usually there is only one -dev version (1-dev), but there may be more
	  if for example there is a wordcode compatibility break, in which case
	  the sequence would be something like 1-dev, 2-dev, 3-test, .... No
	  special release process is associated with a -dev version bump.
	- Usually at least one -test version is released for public testing in
	  the lead-up to the final release of the next stable version.

  README should document compatibility-breaking changes. Generally, NEWS should
  document new features and major bug fixes (but not routine fixes or changes to
  completion/contrib functions).

  For -test releases, you may update the FAQ, README, etc., to refer to the
  upcoming stable version number.

- Commit those changes with an "unposted" ChangeLog entry.

	git commit -am "Test release: 5.8.1.2-test." &&
		zshdev-add-nnnnn-and-changelog unposted
	# (Everyone has a different way of getting the "unposted" magic string
	# into ChangeLog and the log message.  This script is how I do it; YMMV;
	# see Etc/zsh-development-guide for alternative scripts.)

- Create signed git tag named "zsh-5.8.1..." (not "5.8.1...")

	git tag --sign -m "Tag version zsh-5.8.1.2-test." zsh-5.8.1.2-test

- If the tagged release is a stable release (as opposed to a test release):

	vi Config/version.mk # bump to 5.9.0.1-dev and tomorrow's date
	git commit -am "Post-release version bump." &&
		zshdev-add-nnnnn-and-changelog unposted
		# or local equivalent (see above)

- Create tarball:

	git checkout zsh-5.8.1.2-test
	git diff HEAD # ensure no local mods
	rm -f Doc/help.txt Doc/help/[_a-zA-Z0-9]* # some devs have had issues with these
	Util/preconfig && ./configure ...
	make -C Etc
	make -C Doc everything
	make tarxz-doc tarxz-src
	for i in zsh*.tar.?z ; do gpg -ab -- $i ; done

- [one time step] Add your key to http://zsh.sf.net/Arc/source.html; see README
  in the 'web' repository for how to do this.  Its URL is:

	git clone git://git.code.sf.net/p/zsh/web
	git clone ssh://git.code.sf.net/p/zsh/web

- [one time step] Add your key to the Keys/ directory in the 'web' repository, using
  `gpg --armor --export $YourPublicKeyFingerprint`.

- Create the keyring:

        cat web.git/Keys/*.asc > zsh-keyring.asc

- Upload to sf.net:

	Test releases go to the "zsh-test" directory.
	Stable releases to zsh/ and zsh-doc/.
	For stable releases only, after uploading, select the tar.xz artifact
	under zsh/, press the 🛈 button ("View Details") to its right, and press
	[Select All] next to "Default Download For:".  This should cause sf.net
	to offer that artifact in the "Looking for the latest version?" line.

  You should upload five files:

        zsh-5.8.tar.xz
        zsh-5.8.tar.xz.asc
        zsh-doc-5.8.tar.xz
        zsh-doc-5.8.tar.xz.asc
        zsh-keyring.asc

        (TODO: what about MD5SUM, FAQ, META-FAQ, all in www.zsh.org/pub/?)

  Note that zsh-keyring.asc is fine to just overwrite, since it's only ever
  appended to, and in any case the underlying Keys/*.asc files are in version
  control.

  TODO: link to zsh-keyring.asc from Arc/source.html and elsewhere

- If the new release is a stable release, update zsh.sf.net:

	# Move into the 'web' repository mentioned above
	cd /path/to/web/repo
	git pull

	# Review the README, in case there is any new information there
	cat README

	# Run release.zsh to update the documentation from the main repository
	# (making sure you still have checked out the tag you created!)
	ZSHPATH=/path/to/zsh/repo ./release.zsh

	# Commit changes
	git commit -am 'Doc, FAQ, Intro: Update for <version>' # replace <version>

	# Update the files mentioned in the release.zsh instructions (just
	# adhere to the existing structure/format)
	$EDITOR index.html
	$EDITOR News/index.html
	$EDITOR releases.html

	# Run release-update-versions.zsh to update the names and sizes of the
	# files listed on the documentation index and source page
	./release-update-versions.zsh <version> # replace <version>

	# Commit changes
	git commit -am 'Update downloads, notes, etc., for <version>' # replace <version>

	# Tag and push changes
	git tag -sm 'Release of zsh <version>' zsh-<version> # replace <version>
	git push

	# Post changes; see web/README for the full rsync command. When in
	# doubt, use `rsync -n` to perform a dry run. Note that changes may take
	# several minutes to appear afterwards
	rsync ...

- For stable releases, upload the build artefacts to zsh.org/pub; you may need
  assistance from another dev if you don't have access to do this.

- Post to -workers@

- After a day or so post to:

	-users@, if test release;
	-announce@, if stable release.