nixos/doc/releases: update the docs as promised
This goes through a recent example of 19.09 (because the workflow should be everchanging, so our example needs to be recent). Lots of changes, just read idk.
This commit is contained in:
worldofpeace
Jon
parent
c9745a5875
commit
d9c33b2ea4
|
|
@ -8,24 +8,26 @@
|
|||
<title>Release process</title>
|
||||
|
||||
<para>
|
||||
Going through an example of releasing NixOS 17.09:
|
||||
Going through an example of releasing NixOS 19.09:
|
||||
</para>
|
||||
|
||||
<section xml:id="one-month-before-the-beta">
|
||||
<title>One month before the beta</title>
|
||||
|
||||
<itemizedlist spacing="compact">
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
Send an email to the nix-devel mailinglist as a warning about upcoming
|
||||
beta "feature freeze" in a month.
|
||||
Create an announcement on <link xlink:href="https://discourse.nixos.org">Discourse</link> as a warning about upcoming beta <quote>feature freeze</quote> in a month. <link xlink:href="https://discourse.nixos.org/t/nixos-19-09-feature-freeze/3707">See this post as an example</link>.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Discuss with Eelco Dolstra and the community (via IRC, ML) about what
|
||||
will reach the deadline. Any issue or Pull Request targeting the release
|
||||
should be included in the release milestone.
|
||||
Discuss with Eelco Dolstra and the community (via IRC, ML) about what will reach the deadline. Any issue or Pull Request targeting the release should be included in the release milestone.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Remove attributes that we know we will not be able to support, especially if there is a stable alternative. E.g. Check that our Linux kernels’ <link xlink:href="https://www.kernel.org/category/releases.html">projected end-of-life</link> are after our release projected end-of-life.
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
|
|
@ -34,113 +36,127 @@
|
|||
<section xml:id="at-beta-release-time">
|
||||
<title>At beta release time</title>
|
||||
|
||||
<itemizedlist spacing="compact">
|
||||
<orderedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
<link xlink:href="https://github.com/NixOS/nixpkgs/issues/13559">Create
|
||||
an issue for tracking Zero Hydra Failures progress. ZHF is an effort to
|
||||
get build failures down to zero.</link>
|
||||
From the master branch run:
|
||||
</para>
|
||||
</listitem>
|
||||
</orderedlist>
|
||||
|
||||
<programlisting>
|
||||
# git checkout -b release-19.09
|
||||
</programlisting>
|
||||
|
||||
<orderedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
<link xlink:href="https://github.com/NixOS/nixpkgs/commit/10e61bf5be57736035ec7a804cb0bf3d083bf2cf#diff-9c798092bac0caeb5c52d509be0ca263R69">Bump the <literal>system.defaultChannel</literal> attribute in <literal>nixos/modules/misc/version.nix</literal></link>
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>git tag -a -s -m "Release 17.09-beta" 17.09-beta
|
||||
&& git push origin 17.09-beta</literal>
|
||||
<link xlink:href="https://github.com/NixOS/nixpkgs/commit/10e61bf5be57736035ec7a804cb0bf3d083bf2cf#diff-831e8d9748240fb23e6734fdc2a6d16eR15">Update <literal>versionSuffix</literal> in <literal>nixos/release.nix</literal></link>
|
||||
</para>
|
||||
</listitem>
|
||||
</orderedlist>
|
||||
|
||||
<para>
|
||||
To get the commit count, use the following command:
|
||||
</para>
|
||||
|
||||
<programlisting>
|
||||
git rev-list --count release-19.09
|
||||
</programlisting>
|
||||
|
||||
<orderedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
From the master branch run <literal>git checkout -b
|
||||
release-17.09</literal>.
|
||||
Edit changelog at <literal>nixos/doc/manual/release-notes/rl-1909.xml</literal>.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<link xlink:href="https://github.com/NixOS/nixos-org-configurations/pull/18">
|
||||
Make sure a channel is created at https://nixos.org/channels/. </link>
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<link xlink:href="https://github.com/NixOS/nixpkgs/compare/bdf161ed8d21...6b63c4616790">
|
||||
Bump the <literal>system.defaultChannel</literal> attribute in
|
||||
<literal>nixos/modules/misc/version.nix</literal> </link>
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<link xlink:href="https://github.com/NixOS/nixpkgs/commit/d6b08acd1ccac0d9d502c4b635e00b04d3387f06">
|
||||
Update <literal>versionSuffix</literal> in
|
||||
<literal>nixos/release.nix</literal></link>, use
|
||||
<literal>git rev-list --count 17.09-beta</literal>
|
||||
to get the commit count.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>echo -n "18.03" > .version</literal> on master.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<link xlink:href="https://github.com/NixOS/nixpkgs/commit/b8a4095003e27659092892a4708bb3698231a842">
|
||||
Pick a new name for the unstable branch. </link>
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Create a new release notes file for the upcoming release + 1, in this
|
||||
case <literal>rl-1803.xml</literal>.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Create two Hydra jobsets: release-17.09 and release-17.09-small with
|
||||
<literal>stableBranch</literal> set to false.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Remove attributes that we know we will not be able to support,
|
||||
especially if there is a stable alternative. E.g. Check that our
|
||||
Linux kernels'
|
||||
<link xlink:href="https://www.kernel.org/category/releases.html">
|
||||
projected end-of-life</link> are after our release projected
|
||||
end-of-life
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Edit changelog at
|
||||
<literal>nixos/doc/manual/release-notes/rl-1709.xml</literal> (double
|
||||
check desktop versions are noted)
|
||||
</para>
|
||||
<itemizedlist spacing="compact">
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
Get all new NixOS modules <literal>git diff
|
||||
release-17.03..release-17.09 nixos/modules/module-list.nix|grep
|
||||
^+</literal>
|
||||
Get all new NixOS modules:
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<programlisting>
|
||||
git diff release-19.03..release-19.09 nixos/modules/module-list.nix| grep ^+
|
||||
</programlisting>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
Note systemd, kernel, glibc and Nix upgrades.
|
||||
Note systemd, kernel, glibc, desktop environment, and Nix upgrades.
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
Tag the release:
|
||||
</para>
|
||||
</listitem>
|
||||
</orderedlist>
|
||||
|
||||
<programlisting>
|
||||
# git tag --annotate --message="Release 19.09-beta" 19.09-beta
|
||||
# git push upstream 19.09-beta
|
||||
</programlisting>
|
||||
|
||||
<orderedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
<link xlink:href="https://github.com/NixOS/nixpkgs/commit/01268fda85b7eee4e462c873d8654f975067731f#diff-2bc0e46110b507d6d5a344264ef15adaR1">On the <literal>master</literal> branch, increment the <literal>.version</literal> file</link>
|
||||
</para>
|
||||
</listitem>
|
||||
</orderedlist>
|
||||
|
||||
<programlisting>
|
||||
# echo -n "20.03" > .version
|
||||
</programlisting>
|
||||
|
||||
<orderedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
<link xlink:href="https://github.com/NixOS/nixpkgs/commit/01268fda85b7eee4e462c873d8654f975067731f#diff-03f3d41b68f62079c55001f1a1c55c1dR137">Update <literal>codeName</literal> in <literal>lib/trivial.nix</literal></link> This will be the name for the next release.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<link xlink:href="https://github.com/NixOS/nixpkgs/commit/01268fda85b7eee4e462c873d8654f975067731f#diff-e7ee5ff686cdcc513ca089d6e5682587R11">Create a new release notes file for the upcoming release + 1</link>, in our case this is <literal>rl-2003.xml</literal>.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Contact the infrastructure team to create the necessary Hydra Jobsets.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<link xlink:href="https://github.com/NixOS/nixos-org-configurations/blob/master/channels.nix">Create a channel at https://nixos.org/channels by creating a PR to nixos-org-configurations, changing <literal>channels.nix</literal></link>
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Get all Hydra jobsets for the release to have their first evaluation.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<link xlink:href="https://github.com/NixOS/nixpkgs/issues/13559">Create an issue for tracking Zero Hydra Failures progress. ZHF is an effort to get build failures down to zero.</link>
|
||||
</para>
|
||||
</listitem>
|
||||
</orderedlist>
|
||||
</section>
|
||||
|
||||
<section xml:id="during-beta">
|
||||
<title>During Beta</title>
|
||||
|
||||
<itemizedlist spacing="compact">
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
Monitor the master branch for bugfixes and minor updates and cherry-pick
|
||||
them to the release branch.
|
||||
Monitor the master branch for bugfixes and minor updates and cherry-pick them to the release branch.
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
|
|
@ -149,7 +165,7 @@
|
|||
<section xml:id="before-the-final-release">
|
||||
<title>Before the final release</title>
|
||||
|
||||
<itemizedlist spacing="compact">
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
Re-check that the release notes are complete.
|
||||
|
|
@ -157,21 +173,17 @@
|
|||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Release Nix (currently only Eelco Dolstra can do that).
|
||||
<link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/installer/tools/nix-fallback-paths.nix">
|
||||
Make sure fallback is updated. </link>
|
||||
Release Nix (currently only Eelco Dolstra can do that). <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/installer/tools/nix-fallback-paths.nix">Make sure fallback is updated.</link>
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<link xlink:href="https://github.com/NixOS/nixpkgs/commit/40fd9ae3ac8048758abdcfc7d28a78b5f22fe97e">
|
||||
Update README.md with new stable NixOS version information. </link>
|
||||
<link xlink:href="https://github.com/NixOS/nixpkgs/commit/40fd9ae3ac8048758abdcfc7d28a78b5f22fe97e">Update README.md with new stable NixOS version information.</link>
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Change <literal>stableBranch</literal> to <literal>true</literal> in Hydra and wait for
|
||||
the channel to update.
|
||||
Change <literal>stableBranch</literal> to <literal>true</literal> in Hydra and wait for the channel to update.
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
|
|
@ -180,76 +192,140 @@
|
|||
<section xml:id="at-final-release-time">
|
||||
<title>At final release time</title>
|
||||
|
||||
<itemizedlist spacing="compact">
|
||||
<orderedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>git tag -s -a -m "Release 15.09" 15.09</literal>
|
||||
Update <quote>Chapter 4. Upgrading NixOS</quote> section of the manual to match new stable release version.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Update "Chapter 4. Upgrading NixOS" section of the manual to match
|
||||
new stable release version.
|
||||
Update <literal>rl-1909.xml</literal> with the release date.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Update the
|
||||
<link xlink:href="https://github.com/NixOS/nixos-homepage/commit/2a37975d5a617ecdfca94696242b6f32ffcba9f1"><code>NIXOS_SERIES</code></link>
|
||||
in the
|
||||
<link xlink:href="https://github.com/NixOS/nixos-homepage">nixos-homepage</link>
|
||||
repository.
|
||||
Tag the final release
|
||||
</para>
|
||||
</listitem>
|
||||
</orderedlist>
|
||||
|
||||
<programlisting>
|
||||
# git tag --annotate --message="Release 19.09" 19.09
|
||||
# git push upstream 19.09
|
||||
</programlisting>
|
||||
|
||||
<orderedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
Update <link xlink:href="https://github.com/NixOS/nixos-homepage">nixos-homepage</link> for the release.
|
||||
</para>
|
||||
<orderedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
<link xlink:href="https://github.com/NixOS/nixos-homepage/blob/47ac3571c4d71e841fd4e6c6e1872e762b9c4942/Makefile#L1">Update <literal>NIXOS_SERIES</literal> in the <literal>Makefile</literal></link>.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<link xlink:href="https://github.com/NixOS/nixos-homepage/blob/47ac3571c4d71e841fd4e6c6e1872e762b9c4942/nixos-release.tt#L1">Update <literal>nixos-release.tt</literal> with the new NixOS version</link>.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<link xlink:href="https://github.com/NixOS/nixos-homepage/blob/47ac3571c4d71e841fd4e6c6e1872e762b9c4942/flake.nix#L10">Update the <literal>flake.nix</literal> input <literal>released-nixpkgs</literal> to 19.09</link>.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Run <literal>./update.sh</literal> (this updates flake.lock to updated channel).
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<link xlink:href="https://github.com/NixOS/nixos-homepage/blob/a5626c71c03a2dd69086564e56f1a230a2bb177a/logo/nixos-logo-19.09-loris-lores.png">Add a compressed version of the NixOS logo for 19.09</link>.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<link xlink:href="https://github.com/NixOS/nixos-homepage/commit/a5626c71c03a2dd69086564e56f1a230a2bb177a#diff-9cdc6434d3e4fd93a6e5bb0a531a7c71R5">Compose a news item for the website RSS feed</link>.
|
||||
</para>
|
||||
</listitem>
|
||||
</orderedlist>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Get number of commits for the release: <literal>git log
|
||||
release-14.04..release-14.12 --format=%an|wc -l</literal>
|
||||
Create a new topic on <link xlink:href="https://discourse.nixos.org/">the Discourse instance</link> to announce the release.
|
||||
</para>
|
||||
</listitem>
|
||||
</orderedlist>
|
||||
|
||||
<para>
|
||||
You should include the following information: - Number of commits for the release: <literal>bash git log release-19.03..release-19.09 --format=%an | wc -l</literal>
|
||||
</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
Commits by contributor: <literal>git log release-14.04..release-14.12
|
||||
--format=%an|sort|uniq -c|sort -rn</literal>
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Create a new topic on <link xlink:href="https://discourse.nixos.org/">the
|
||||
Discourse instance</link> to announce the release with the above information.
|
||||
Best to check how previous email was formulated to see what needs to be
|
||||
included.
|
||||
Commits by contributor:
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<programlisting>
|
||||
git shortlog -sn release-19.03..release-19.09
|
||||
</programlisting>
|
||||
|
||||
<para>
|
||||
Best to check how the previous post was formulated to see what needs to be included.
|
||||
</para>
|
||||
</section>
|
||||
</section>
|
||||
<section xml:id="release-managers">
|
||||
<section xml:id="release-management-team">
|
||||
<title>Release Management Team</title>
|
||||
|
||||
<para>
|
||||
For each release there are two release managers. After each release the
|
||||
release manager having managed two releases steps down and the release
|
||||
management team of the last release appoints a new release manager.
|
||||
For each release there are two release managers. After each release the release manager having managed two releases steps down and the release management team of the last release appoints a new release manager.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
This makes sure a release management team always consists of one release
|
||||
manager who already has managed one release and one release manager being
|
||||
introduced to their role, making it easier to pass on knowledge and
|
||||
experience.
|
||||
This makes sure a release management team always consists of one release manager who already has managed one release and one release manager being introduced to their role, making it easier to pass on knowledge and experience.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Release managers for the current NixOS release are tracked by GitHub team
|
||||
<link xlink:href="https://github.com/orgs/NixOS/teams/nixos-release-managers/members"><literal>@NixOS/nixos-release-managers</literal></link>.
|
||||
Release managers for the current NixOS release are tracked by GitHub team <link xlink:href="https://github.com/orgs/NixOS/teams/nixos-release-managers/members"><literal>@NixOS/nixos-release-managers</literal></link>.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
A release manager's role and responsibilities are:
|
||||
A release manager’s role and responsibilities are:
|
||||
</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem><para>manage the release process</para></listitem>
|
||||
<listitem><para>start discussions about features and changes for a given release</para></listitem>
|
||||
<listitem><para>create a roadmap</para></listitem>
|
||||
<listitem><para>release in cooperation with Eelco Dolstra</para></listitem>
|
||||
<listitem><para>decide which bug fixes, features, etc... get backported after a release</para></listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
manage the release process
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
start discussions about features and changes for a given release
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
create a roadmap
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
release in cooperation with Eelco Dolstra
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
decide which bug fixes, features, etc… get backported after a release
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</section>
|
||||
<section xml:id="release-schedule">
|
||||
|
|
|
|||
Loading…
Reference in a new issue