From b6f756768b38a8759eb0febaa45def336ceeab96 Mon Sep 17 00:00:00 2001
From: Virgile Prevosto <virgile.prevosto@cea.fr>
Date: Fri, 13 Dec 2024 18:20:11 +0100
Subject: [PATCH] [releaseman] Instructions for releasing plug-ins together
with Frama-C
---
doc/release/branch.tex | 11 +++++++++++
doc/release/deploy.tex | 38 ++++++++++++++++++++++++++++++++++++++
doc/release/validation.tex | 10 ++++++++++
3 files changed, 59 insertions(+)
diff --git a/doc/release/branch.tex b/doc/release/branch.tex
index 0fe63a2812..e8621413e2 100644
--- a/doc/release/branch.tex
+++ b/doc/release/branch.tex
@@ -4,12 +4,15 @@
That is the procedure for forking the release from \texttt{master}.
\section{Creating the milestones}
+\label{sec:creating-milestones}
Create the milestone for the next releases on \textsf{Gitlab},
in the Frama-C group. They will be used for development that will not
be integrated into the upcoming release.
\expertise{François, Julien}.
+
\section{Creating the branch}
+\label{sec:creating-branch}
\textbf{Note:} You must be member of the GitLab groups "frama-c", "dev" and have
access to each plugin of continuous integration.
@@ -41,6 +44,7 @@ allowed to push/merge).
sure to set their targeted branch to \texttt{stable/release}.
\section{Retargeting Merge Requests}
+\label{sec:retarg-merge-requ}
Another command of \texttt{frama-ci} allows retargeting
the opened merge requests associated to the milestone corresponding
@@ -52,6 +56,7 @@ frama-ci-retarget-merge-requests --token=$TOKEN \
\end{shell}
\section{GitLab issues}
+\label{sec:gitlab-issues}
{\em This is currently done periodically in specific Frama-C meetings, so only
a final check is usually necessary.}~\\
@@ -66,6 +71,7 @@ severity, the issues should be tagged with the current release, or with the next
one.
\section{Version}
+\label{sec:version}
On the new \texttt{stable} branch, execute the script:
\begin{verbatim}
@@ -100,6 +106,7 @@ This will:
Commit this change and push.
\section{External plugins}
+\label{sec:external-plugins}
List of external plugins repo names:
\begin{itemize}
@@ -127,6 +134,7 @@ request targetting \texttt{stable/release} on each plugin and assign your co-rm.
This changes will need to be merged on master's branches later.
\section{Copyright}
+\label{sec:copyright}
Check that the date in copyright headers is correct. If not then:
\begin{itemize}
@@ -144,6 +152,9 @@ Check that the date in copyright headers is correct. If not then:
\item Check if some copyrights are left to update by \texttt{grep}-ing the date in the sources: \texttt{grep -r -e "-yyyy" .}
\end{itemize}
+This must also be checked for Frama-Clang and MetAcsl if they are also to be
+released.
+
%%%Local Variables:
%%%TeX-master: "release"
%%%End:
diff --git a/doc/release/deploy.tex b/doc/release/deploy.tex
index 0b65e17fbe..d50bb58eef 100644
--- a/doc/release/deploy.tex
+++ b/doc/release/deploy.tex
@@ -6,6 +6,7 @@ starting this stage. The tasks listed in this section are mostly performed by
the Release Manager.
\section{Release pipeline}
+\label{sec:release-pipeline}
Go to the Build $\rightarrow$ Pipelines section of GitLab. Start the release pipeline:
\begin{itemize}
@@ -40,6 +41,7 @@ release and the release should be available in
version in \url{https://git.frama-c.com/pub/frama-c/-/tags}.
\section{Check the website}
+\label{sec:check-website}
Once the pipeline for the website has run, open \texttt{https://pub.frama-c.com}.
@@ -102,13 +104,37 @@ If everything is fine, merge the website and ask a website maintainer to put it
online (\expertise{Allan, Augustin}).
\section{Public GitLab}
+\label{sec:public-gitlab}
Open the generated wiki page (visible in the public website activity). Check the
links (files are available only once the website has been put online). If
everything is fine, edit the main wiki page and the sidebar with a link to the
page (\url{https://git.frama-c.com/pub/frama-c/-/wikis/home}).
+\section{External Plug-in Release}
+\label{sec:ext-plug-ins-release}
+
+If a release of Frama-Clang and MetAcsl is scheduled together
+with the main Frama-C release, you can now launch the release pipelines
+on their respective repositories (\texttt{frama-c/frama-clang} and
+\texttt{frama-c/meta}), with the same protocol as for the main
+Frama-C repository described in Sect.~\ref{sec:release-pipeline}.
+The only difference is that there is only a single \texttt{release}
+\todo{it would be good to split the script in several sub-jobs} task.
+Then, check the website MR that have been created (one for each
+plug-in), and merge them if everything is alright.
+
+In particular, the \texttt{\_fc-plugins/frama-clang.md} needs manual
+update\todo{reword this page to avoid this manual step}.
+
+Note that these releases can be done at a later point and independently from
+Frama-C. If you happen to release a plug-ins after the PR for Frama-C has been
+merged on opam repository (see Sect.~\ref{sec:opam-package}), a new PR will be
+opened for the plug-in. Otherwise, the same branch will be used to create all
+the packages.
+
\section{Announcements}
+\label{sec:announcements}
\begin{itemize}
\item Send an e-mail to \texttt{frama-c-discuss} announcing the release.
@@ -119,6 +145,7 @@ page (\url{https://git.frama-c.com/pub/frama-c/-/wikis/home}).
\end{itemize}
\section{Opam package}
+\label{sec:opam-package}
You'll need a GitHub account to create a pull request on the official opam
repository\footnote{\texttt{ocaml/opam-repository.git}}. Go to the \FramaC
@@ -126,7 +153,17 @@ GitHub organization opam repository (\url{https://github.com/Frama-C/opam-reposi
Find the branch corresponding to the release and create the pull-request on the
official opam repository.
+As mentioned in Sect.~\ref{sec:ext-plug-ins-release}, the PR can contain
+plug-in(s) package(s) in addition to the Frama-C package itself if plug-ins
+have also been released.
+
+Once the PR has been merged, make sure that the branch is removed from
+the fork in
+\texttt{Frama-C/opam-repository}\todo{If possible in github's REST API,
+make sure that the merge will erase the branch automatically}.
+
\section{Other repositories to update}
+\label{sec:other-repos-update}
Check if other \FramaC (and related) repositories need to be updated:
@@ -138,6 +175,7 @@ Check if other \FramaC (and related) repositories need to be updated:
\end{itemize}
\section{Docker image preparation}
+\label{sec:dock-image-prep}
This section only applies to non-beta releases.
diff --git a/doc/release/validation.tex b/doc/release/validation.tex
index aa67612e94..d048932e65 100644
--- a/doc/release/validation.tex
+++ b/doc/release/validation.tex
@@ -219,6 +219,16 @@ Note that an extra pipeline will be run when the tag is pushed, and it will
likely fail due to external plugins. This is not a problem (if you really want
to avoid it, you can create and push the tag to each external plug-in).
+\section{External Plug-in Validation}
+
+In case a release of Frama-Clang and/or MetAcsl is scheduled together with the
+Frama-C release itself, their respective \texttt{CHANGELOG.md} must be checked to confirm
+that they contain a section corresponding to the upcoming release.
+
+For Frama-Clang, the files \texttt{FCLANG\_VERSION}, \texttt{FC\_VERSION}, and
+\texttt{FC\_VERSION\_NAME} must also be checked. If you have applied the
+appropriate script in Sect.~\ref{sec:external-plugins}, this should be the case.
+
%%%Local Variables:
%%%TeX-master: "release"
%%%End:
--
GitLab