website.tex

\chapter{The Website Stage}

Where all our efforts goes on the web.  There are two very different
tasks for \FramaC to go online.  Authoring the web site pages is the
responsibility of the developers and the release manager. Publishing
the web site can only be performed by authorized people, who may not
be the release manager.

\section{Requirements}

You need the following applications:
\begin{itemize}
\item \texttt{pandoc}>=2.0; if your distribution has an older
  version, you can find installation instructions at
  \url{https://github.com/jgm/pandoc/blob/master/INSTALL.md}
\item \texttt{tidy}
\item \texttt{linkchecker}
\end{itemize}

\section{Authoring the Pages}

The website sources are in \texttt{src}. Go to this directory.

\subsection{Editing Web Pages}

You should consult and/or improve the \texttt{README} for style
instructions, and edit \texttt{*.prehtml} files.

Compile the web pages with:
\begin{shell}[gobble=2]
  \$ make local
\end{shell}

This way, you get a snapshot of the web-site in \texttt{src},
without any downloadable resources. You can start browsing at
\texttt{index.html}. Note that the new news and download pages still
need to be manually updated.

\subsection{Adding News}
The news are defined in the \texttt{news.def} page. All the news
are published in the \textsf{RSS} of \FramaC. Only the first news are
published on the home page of the web site. The limit is marked with:
\begin{shell}
  <#def end-of-html-news></#def>
\end{shell}

Move it upward in order to keep only few interesting news on the
\FramaC home page.

\section{Adding the new Release}

From the build stage, the files to distributed are available in the
\texttt{website} repository and already ready to commit (look at
\texttt{git status}). The release manager should update the web pages
of the \emph{download} and \emph{support} sections to make the new
release and documentation available.

The current (\emph{awkward}) procedure is as follows:
\begin{enumerate}
\item In case a new release of ACSL is done together with Frama-C's release;
  \begin{itemize}
  \item copy the ACSL manual using the ``numeric'' version
    (\texttt{www/download/acsl\_x.y.pdf}) and add it via \texttt{git add}
    (\texttt{git lfs} should automatically handle it, since it's a .pdf);
  \item check that \texttt{www/download/acsl.pdf} was updated by the build script;
%  \item update \texttt{src/download.def} (can't find where???);
  \item update \texttt{src/acsl.prehtml}: add a new entry for the new version of ACSL
 \end{itemize}
\item Copy the file \texttt{INSTALL.md} from Frama-C to
  \texttt{INSTALL-NAME.md} where \texttt{NAME} is the version name of the
  distribution.
\item Update the \texttt{Makefile} in \texttt{src}:
  \begin{itemize}
  \item Add to variable \texttt{PAGES} the new files to export (at least
    install-<version>.html, following the pattern already present). This will
    create a target that will generate it from the previous .md file.
  \item Add the previous latest version to the \texttt{DOWNLOAD\_PAGES}
    variable for adding a specific downloading page related to that
    previous release.
  \end{itemize}
\item Update also some macros of \texttt{download.def} file:
  \begin{enumerate}
  \item Add an entry after the \texttt{selector-previous-versions} macro.
  \item Update macros \texttt{latest-No-Version}, \texttt{previous-version} and
    \texttt{previous-No-Version}.
  \item Move the definition of \texttt{download-last-version} macro
  to a new macro \texttt{download\_NAME}, where \texttt{NAME}
  is the version name added to \texttt{DOWNLOAD\_PAGES} variable of the
  \texttt{Makefile}.
  \item Update the definition of \texttt{download-last-version} macro.
  \item Add a new \texttt{selector-download\_NAME} macro.
  \item Add a link back to that downloading page into the \texttt{selector-download\_PREVIOUS\_NAME} macro.
  \item Check the occurrences of references to the previous release
  resources, and update them. A good practice is to \texttt{grep}
  \texttt{*.prehtml} \texttt{*.def} against the name of the release.
  You should at least update the links to reference documentation from the
  \texttt{support.prehtml} page.
  \end{enumerate}
\item Build the web site:
  \begin{shell}[gobble=4]
    \$ make local
    \$ make distrib
  \end{shell}
  You get a snapshot of the repository in the \texttt{www} directory.
  Before going there, check for compliance with \textsf{W3C} and link
  consistency by running:
  \begin{shell}
    \$ make check_link
  \end{shell}
  Run it and check the result, fixing broken links if necessary.
  Go to \texttt{../www}, then open \texttt{index.html} and test the website
  carefully, especially:
  \begin{itemize}
  \item the new Downloads page;
  \item the previous Downloads page;
  \item Compilation instructions;
  \item Changelog (check parsing, for all plug-ins).
  \end{itemize}

\item Commit the web site:
  \begin{shell}
    \$ cd ..
    \$ # manually check that only wanted new files are present
    \$ git add .
    \$ git checkout -b \$RELEASE
    \$ git commit -m "updating distrib website"
  \end{shell}
\end{enumerate}

\section{Publishing}

You have to create a merge request on the website repository that will be published when Florent
accepts it on the online branch.

\textbf{Note:} the following steps are done only after the release is live on the website.

\section{Announcements}

\begin{itemize}
\item Send an e-mail to \texttt{frama-c-discuss} announcing the release.
\item Tweet the release, pointing to the Downloads page.
\item Ideally, a blog post should arrive in a few days, with some interesting
  new features.
\end{itemize}

\section{Opam package}

You'll need a GitHub account to create a pull request on the official opam repository,
\texttt{ocaml/opam-repository.git}.

\begin{itemize}
\item Clone \texttt{opam-repository}: \texttt{git clone git@github.com:ocaml/opam-repository.git}
\item Make sure you are on \texttt{master} and your branch is up-to-date
\item Create a new directory: \\
  \texttt{packages/frama-c/frama-c.<version>} \\
\item Copy the file \texttt{opam/opam} from the release
 to the opam repository clone in: \\
 \texttt{packages/frama-c/frama-c.<version>/opam}
\item Compute the MD5sum of the .tar.gz file and update the \texttt{opam} file
with the following entry:
\begin{verbatim}
url {
  src: "https://frama-c.com/download/frama-c-<version>-<version-name>.tar.gz"
  checksum: "md5=<xxxxxx>"
}
\end{verbatim}
You can provide \verb|sha256| and/or \verb|sha512| checksums as well if
you wish.
\item (optional) Check locally that everything is fine:
\begin{verbatim}
opam switch create local <some-ocaml-compiler-version>
opam repository add local <path-to-repository-clone>
opam repository set-repos local
opam install frama-c
\end{verbatim}
(of course, if you already create a local switch before and it uses your
local version of the repository, you just have to switch to it).

\textbf{Note:} uncommitted changes are ignored by \texttt{opam repository};
you have to locally commit them before \texttt{opam update} will take them into
account.

\item Create a branch with any name you want (e.g. frama-c.<version>) and push it to your remote Github
\item Create a pull request to opam-repository. If all tests pass,
  someone from opam should merge it for you.
  \textbf{Note:} some opam tests may fail due to external circumstances; if the
  error log makes no sense to you, wait to see if someone will contact you
  about it, or ask directly on the merge request.
\end{itemize}

\section{Updating pub/frama-c}

You'll need to be member of the \texttt{pub/frama-c} project to be able to
commit to it.

\begin{itemize}
\item add the \texttt{pub/frama-c} remote to your Git clone;
\item make sure the last commit is tagged (either a release candidate, or a
  final release);
\item push the stable/\texttt{<codename>} branch to the \texttt{pub} remote.
\end{itemize}

({\em Non-beta only}) After pushing the tag to Gitlab, go to the Releases page
and create a release for the tag.

\section{Updating the BTS}

\expertise{Usually Julien performs this step. Soon to be obsoleted.}

Each task marked as \texttt{Resolved} and really resolved in this release (say
\texttt{VERSION}) must be marked as \texttt{Fixed in Version VERSION}, then
\texttt{Closed}.

The just released \texttt{VERSION} must be marked as \texttt{released} in the
Section \texttt{manage} while an entry for the next one must be added (if not
already done).

Finally have a look at each still opened task in order to see what should be
resolved in the next release.

%% \section{Update the Wiki}

%% Update references of the Wiki, especially pointers to manuals of this page:
%% \url{http://bts.frama-c.com/dokuwiki/doku.php?id=mantis:frama-c:publications}

\section{Other repositories to update}

Check if other Frama-C (and related) repositories need to be updated:

\begin{itemize}
\item \texttt{acsl-language/acsl} (if last minute patches were applied)
\item \texttt{pub/open-source-case-studies}
\item \texttt{pub/sate-6}
\item other \texttt{pub} repositories related to Frama-C...
\end{itemize}

\section{Preparing the Next Release}

Just update the \texttt{VERSION} file in \texttt{master}, by adding
\texttt{"+dev"}. Do not add any newline at the end of the
\texttt{VERSION} file.

%%% Local Variables:
%%% mode: latex
%%% TeX-master: "release"
%%% End: