Skip to content

Commit a80d396

Browse files
ndokosndokos
committed
Release docs
- v0.72.0 release notes - v0.72.1.release notes - release checklist (greatly expanded but still WIP) - sample announcement (TBD) PBENCH-1129
1 parent 7d727fe commit a80d396

File tree

4 files changed

+530
-0
lines changed

4 files changed

+530
-0
lines changed

‎docs/release/checklist.org

+141
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
#+TITLE: Release checklist
2+
3+
* Clone the release branch
4+
5+
#+begin_src shell
6+
git checkout upstream/b0.72
7+
git branch -u upsream/b0.72
8+
#+end_src
9+
so an update and rebase will get you to the latest commit on the upsream branch.
10+
11+
* Test
12+
** (Step 1) Build an RPM in the COPR -test repo
13+
14+
Make sure that =agent/VERSION= in the branch reflects the release version (e.g. 0.72.0).
15+
That will allow the =make= invocation below to create properly named RPMs (e.g. =pbench-agent-pbench-agent-0.72.0-1gXXXXXXX)
16+
in the appropriate repo (=pbench-0.72-test= in this case)
17+
#+begin_src shell
18+
cd agent/rpm
19+
make copr-test
20+
#+end_src
21+
22+
** (Step 2) Create VMs of various stripes for testing and prep them appropriately
23+
(e.g. ssh keys need to be installed for ansible to work and repos need to be installed (e.g CRB repos on RHEL-8 and RHEL-9 and EPEL repos).
24+
25+
26+
** (Step 3) Run the playbooks to do the prep, repo install, pbench-agent/pbench-systat install, the config of the agent and the firewall rules
27+
TBD
28+
29+
** (Step 4) Run the smoke tests
30+
TBD
31+
32+
** (Step 5) Run end-to-end tests
33+
TBD linpack, uperf, fio: register tools, run the benchmark, clean up the
34+
tools, push the results.
35+
36+
* Lather, rinse, repeat
37+
Repeat steps 3-5 in the [[* Test][Test]] section above until there are no
38+
errors. In general, you /might/ have to rebuild the RPMs in Step 1 if
39+
any changes to pbench code were made, but you probably do not need to
40+
remake the VMs in Step 2, although you might need to either uninstall the
41+
previous RPM or make sure that the build number of the new RPM is
42+
bumped, so that `dnf` will know to update the installed RPM.
43+
44+
* Commit any changes to the release branch
45+
46+
If there are changes to pbench code, issue PRs for them and make
47+
sure that they are merged. You might want to do another run through
48+
the [[* Test][Test]] process before proceeding further.
49+
50+
It may also be necessary to update the ansible roles on Galaxy:
51+
#+begin_src shell
52+
cd agent/ansible
53+
make test
54+
make publish
55+
#+end_src
56+
57+
Galaxy will refuse to update unless the version in
58+
=agent/ansible/collection/galaxy.yml= is bumped (the current version
59+
as of this writing is 1.0.10).
60+
61+
* Write up release notes - submit for review
62+
Revise until everybody is OK with the release notest.
63+
64+
The release notes should contain:
65+
- a short description of the release
66+
67+
- installation notes identifying any user-visible changes to the installation process and the ansible roles
68+
69+
- new commands and major changes to existing commands
70+
71+
- a list of user-visible bug fixes and enhancements to individual programs
72+
73+
- new deprecation notices and retirement notices of previously deprecated items
74+
75+
- an optional section on future directions
76+
77+
- a changelog of all the relevant commits since the last release
78+
79+
The changelog can be obtained using something like =git v0.71.0..HEAD
80+
--oneline --no-decorate=, but it will need to be manually pruned to
81+
include only commits for the relevant component(s).
82+
83+
Nobody will be happy with the release notes but do not sweat it too
84+
much at this point: the release notes will be committed to the branch
85+
after the release is cut and they can be revised again and again, even
86+
after the release.
87+
88+
* Make sure there are no pending updates to the release branch.
89+
The only other change that should go in before the release is cut should be
90+
the version bump in e.g. =agent/VERSION=. Do this in a separate commit.
91+
92+
* Add a tag and cut the release on GitHub, adding the release notes.
93+
From the top level of the repo on Github, click on "Releases" on the RHS.
94+
95+
Click on "Draft a new release" and add a new tag.The tag should have
96+
the form =v0.72.0=. Make sure that it points to the top of the release
97+
branch, presumably to the commit that bumps the version in the VERSION
98+
file.
99+
100+
Modify the release notes to include the correct SHA1 from the top
101+
of the release branch. Do *not* commit the release notes yet.
102+
Instead cut-and-paste the contents to the text box of the new release
103+
and add a title (try to be consistent with earlier releases).
104+
105+
Make sure that the "Set as the latest release" box is checked and then
106+
click on "Publish Release".
107+
108+
* Retest
109+
Redo the [[* Test][Test]] section above in the updated branch, creating the RPMs
110+
in the final COPR repo.
111+
112+
** Rebuild RPMs in the COPR repo for the release
113+
#+begin_src shell
114+
cd agent/rpm
115+
make copr
116+
#+end_src
117+
118+
** Redo steps 3-4
119+
Install the RPMs on the set of VMs and run the smoke tests. If there
120+
are problems, you will have to repeat the whole process up to this
121+
point.
122+
123+
** Build tagged containers
124+
125+
#+begin_src shell
126+
cd agent/containers/images
127+
make everything
128+
make push
129+
make push-latest
130+
#+end_src
131+
132+
** Send announcement out
133+
134+
See the boilerplate =docs/release/sample-announcement.txt= in this
135+
directory for an example.
136+
137+
** Submit post-release PR to the release branch
138+
The commit should contain the updated release notes. If problems are
139+
found later on, the release notes can be updated with more commits and
140+
copied the same way as before into the text box of the release area on
141+
Github.

‎docs/release/sample-announcement.txt

+168
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,168 @@
1+
* Sample announcement for reference
2+
3+
4+
Subject: Release of version 0.71 of the pbench-agent is now available
5+
To: <recipients>
6+
7+
8+
We are pleased to announce the release of version 0.71 of
9+
pbench-agent. There are some gotchas and known problems that are
10+
described first: please read them carefully because you are almost
11+
certainly going to run into one or more of them.
12+
13+
<GOTCHAS>
14+
- The notion of a "default" tool set is being deprecated and will be
15+
removed in the upcoming Pbench Agent v1.0 release. To replace it, the
16+
Pbench Agent is introducing a few named tool sets. See "Default Tool
17+
Set is Deprecated; Named tool sets introduced" in the Release Notes.
18+
19+
- All tools registered prior to installing v0.71.0 must be
20+
re-registered; tools registered locally, or remotely, on a host with
21+
v0.69 or earlier version of the pbench-agent will be ignored. See
22+
"Tool registration kept local to the host where registration happens"
23+
in the Release Notes.
24+
25+
- Note that pbench no longer installs tools: any missing tools will
26+
only be found and reported when you start a run.
27+
28+
<GOTCHAS/>
29+
30+
<KNOWN PROBLEMS>
31+
In addition, there are some known problems with specific distros:
32+
33+
- The (currently unreleased) RHEL 9.1 version has very spotty coverage
34+
in its Subscription Manager repos. Installation of pbench-agent on
35+
it fails with missing basic packages (e.g. bzip2). There are
36+
probably unofficial repos that could be used instead: this is under
37+
investigation.
38+
39+
- Installation on Fedora 36 succeeds but you will not be able to do
40+
anything with it: Python 3.10 changed the way that pip install modules
41+
(it inserts a "local" element in the path), so the PYTHONPATH settings
42+
are wrong and modules cannot be found. This is a larger problem and we
43+
are working on that, but the upshot is that you won't be able to use
44+
Fedora 36 with this release.
45+
46+
- You should upgrade the pbench Ansible roles with
47+
48+
ansible-galaxy collection install --force pbench.agent
49+
50+
If your version of ansible-galaxy does not support --force, delete
51+
the existing roles and install:
52+
53+
rm -rf $HOME/.ansible/collections/ansible_collections/pbench/agent
54+
ansible-galaxy collection install pbench.agent
55+
56+
The current version is 1.0.7. It contains a fix for the CentOS-Stream-8
57+
distro: without that fix, you are not going to be able to use the playbooks
58+
to install on that distro.
59+
60+
- If you are upgrading from v0.69, there is one additional problem:
61+
the v0.69 installation probably installed the `pbench-perl-JSON-XS'
62+
RPM, our own build of perl-JSON-XS which was missing from all RHEL
63+
plaforms. It (and many other perl packages) is now available from
64+
standard repos (EPEL on RHEL7, CRB (Codeready Builder) repo on
65+
RHEL8/9, PowerTools repo on Centos-stream-8/9). However, the
66+
installed `pbench-perl-JSON-XS' on v0.69 conflicts with the official
67+
`perl-JSON-XS', so the RPM installation fails. The workaround is to
68+
erase the `pbench-perl-JSON-XS' RPM before updating to v0.71.0:
69+
70+
$ yum shell
71+
> erase pbench-perl-JSON-XS
72+
> update pbench-agent
73+
74+
That's the best way to do it on a single system, but if you have a
75+
lot of systems that you are installing to, it's probably easier to
76+
use your inventory file to do the erasing with an ad-hoc Ansible
77+
command and then install normally:
78+
79+
ansible -i /path/to/Inventory/file servers -m command -a 'yum erase -y pbench-perl-JSON-XS'
80+
ansible-playbook -i /path/to/Inventory/file pbench-agent-install.yml
81+
82+
- Installing on RHEL 8.4 and 8.5 fails because of the ansible-core
83+
dependency. There are more problems with the ansible package on
84+
RHEL78.4 and 8.5 however: see
85+
86+
https://access.redhat.com/discussions/6962395
87+
88+
If you cannot upgrade to RHEL 8.6, let us know: we might be able to
89+
help.
90+
91+
</KNOWN PROBLEMS>
92+
93+
94+
<ANNOUNCEMENT>
95+
The RPMs are available in the main COPR pbench repo:
96+
97+
https://copr.fedorainfracloud.org/coprs/ndokos/pbench/
98+
99+
We strongly recommend that you use Ansible playbooks to install pbench-agent.
100+
See below for the link to the Installation Guide.
101+
102+
You are going to need an inventory file. Here's a template: just list
103+
the hosts where you want to install pbench-agent in the [servers]
104+
section; nothing else needs to be touched:
105+
106+
[servers]
107+
hostA
108+
hostB
109+
...
110+
111+
[servers:vars]
112+
pbench_repo_name = pbench
113+
fedoraproject_username = ndokos
114+
115+
pbench_key_url = http://git.app.eng.bos.redhat.com/git/perf-dept.git/plain/bench/pbench/agent/{{ pbench_configuration_environment }}/ssh
116+
pbench_config_url = http://git.app.eng.bos.redhat.com/git/perf-dept.git/plain/bench/pbench/agent/{{ pbench_configuration_environment }}/config
117+
118+
After installation, the RPM version reported by `dnf list installed
119+
pbench-agent' should be:
120+
121+
pbench-agent.noarch 0.71.0-3g85910732a @copr-pbench-ndokos
122+
123+
If you had previously installed a test version with a "greater"
124+
version number, you might need to erase it first with `dnf erase
125+
pbench-agent' before this version can be installed: we were a bit
126+
cavalier with the numbering and `dnf' will not install this version if
127+
the version number doesn't allow it.
128+
129+
Containers
130+
----------
131+
132+
Containers have been built based on the RPMs above and are available from
133+
134+
https://quay.io
135+
136+
137+
Release Notes
138+
-------------
139+
140+
The release notes for this release are available at
141+
142+
https://github.com/distributed-system-analysis/pbench/releases/
143+
144+
There are a lot of changes in this release, so we recommend that you
145+
read the release notes carefully.
146+
147+
148+
Installation Guide
149+
------------------
150+
151+
The pbench-agent installation guide is available internally at
152+
153+
http://pbench.perf.lab.eng.bos.redhat.com
154+
155+
156+
Problems
157+
--------
158+
159+
Let us know of any problems you encounter. The best place is the
160+
issue tracker:
161+
162+
https://github.com/distributed-system-analysis/pbench/issues
163+
164+
although for urgent problems the GChat pbench room can be used.
165+
<ANNOUNCEMENT/>
166+
167+
--
168+
The pbench team

0 commit comments

Comments
 (0)