\documentclass{ltxdoc} \errorcontextlines=10 \usepackage{changelog-doc} \author{Rebecca Turner\thanks{Brandeis University; \email{rebeccaturner@brandeis.edu}}} \title{The \cl\ Package} \date{2018-10-29} \begin{document} \maketitle \begin{abstract} Changelogs are important. Unfortunately, there are few facilities for typesetting changelogs in \LaTeX. \cl\ defines a \env{changelog} environment to make changelogs simple and intuitive. For rationale, read \keepachangelog. \end{abstract} \noterepo{9999years/latex-changelog} \tableofcontents \vfill \pagebreak \section{I don't want to read this documentation} Perfectly understandable. \cl\ comes in a ``simple'' flavor: \begin{mdframed} \begin{lstsample}{}{} % \begin{changelog}[author=Rebecca Turner, simple, sectioncmd=\section*] % \begin{version}[v=1.0.0, date=2018-12-28] % \item Cool features % \item Bug fixes % \end{version} % \shortversion{v=0.1.0, date=2018-10-25, changes=Initial beta} % \end{changelog} \end{lstsample} \end{mdframed} And a more organized variant based on \keepachangelog: \begin{mdframed} \begin{lstsample}{}{} % \begin{changelog}[author=Rebecca Turner, sectioncmd=\section*] % \begin{version}[v=1.0.0, date=2018-12-28] % \added % \item Cool features % \fixed % \item Bug fixes % \end{version} % \shortversion{v=0.1.0, date=2018-10-25, changes=Initial beta} % \end{changelog} \end{lstsample} \end{mdframed} \section{Intro} \subsection{Why?} Read \href{https://olivierlacan.com/}{Olivier Lacan}'s lovely site \keepachangelog. To excerpt: \begin{adjustwidth}{1in}{1in} \subsubsection{What is a changelog?} A changelog is a file which contains a curated, chronologically ordered list of notable changes for each version of a project. \subsubsection{Why keep a changelog?} To make it easier for users and contributors to see precisely what notable changes have been made between each release (or version) of the project. \subsubsection{Who needs a changelog?} People do. Whether consumers or developers, the end users of software are human beings who care about what's in the software. When the software changes, people want to know why and how. \end{adjustwidth} \subsection{The competition} It's always good to know the competition. Unfortunately, there isn't much here. Know of another package with similar functionality? Drop me a line or open a pull request! \begin{ctandescription} \pkg{vhistory} provides a decent-looking changelog. However, it's designed for short changes and provides a less-than-elegant interface. Additionally, it's based on the \ctan{ltxtable} package, meaning it makes restrictions on the contents of version information and writes the table to a file. \pkg{holtxdoc} has a decent changelog feature (via Oberdiek's \env{History} and \env{Version} environments), but \ctan{holtxdoc} ``contains some private macros and setup for my needs. Thus do not use it.'' In addition, Oberdiek's changelogs don't support multiple authors. \pkg{gitlog} is an interesting idea, but \ctan{gitlog} ``is a proof-of-concept release to allow users an early evaluation\dots'' Also, \href{https://keepachangelog.com/en/1.0.0/}{friends don't let friends dump git logs into changelogs}. \end{ctandescription} \section{The \env{changelog} environment} \begin{macro}{changelog}\oarg{options}\AfterLastParam Wraps \env{description} while providing the \env{version} environment and the \cs{shortversion} command. In addition to the options shown in table~\ref{opt:changelog}, \meta{options} may contain any of the options for \env{version} (see figure~\ref{opt:version}) as a form of ``partial application''; this may be useful if, for example, most of your versions have the same author. \begin{table}[h] \centering \caption{Options for the \env{changelog} environment} \label{opt:changelog} \begin{adjustwidth}{1in}{1in} \begin{Optionlist} section & Insert a \cs{section} before the changelog? Default: true \\ sectioncmd & Which sectioning command to use? Default: \cs{section} \\ title & What to title the changelog section? Default: \texttt{Changelog} \\ label & What to \cs{label} the section? Default: \texttt{sec:changelog} \\ \end{Optionlist} \end{adjustwidth} \end{table} \end{macro} \begin{macro}{version}\oarg{options}\AfterLastParam Gives a single version; wraps \env{itemize}. If the \option{date} option is absent, the date isn't printed. If the \option{v}/\option{version} option is absent, the date is used in its place. If both \option{version} and \option{date} are absent, the version is shown as \texttt{Unreleased} and \cs{today} is used for the date. \cs{today} isn't ideal (which is to say, not \href{https://en.wikipedia.org/wiki/ISO_8601}{\textsc{iso} 8601} compliant) but it's well-known and easy to redefine.\footnote{Try the \ctan{datetime2} package or \href{https://tex.stackexchange.com/questions/152392/date-format-yyyy-mm-dd}{any of the other solutions here.}} \begin{table}[h] \centering \caption{Options for the \env{version} environment}% \label{opt:version} \begin{adjustwidth}{1in}{1in} \begin{Optionlist} version & The version string for this version \\ v & An alias for \option{version} \\ author & The author(s) of this version \\ date & The date of this version's release \\ yanked & Indicates that the release was revoked due to a ``serious bug or security issue''; prints a visible notice next to the version number \\ simple & Indicates this version isn't split up into \cs{added}, \cs{changed}, etc.\ categories; if this option is given, a \env{version} environment acts like a plain \env{itemize} \\ \end{Optionlist} \end{adjustwidth} \end{table} \end{macro} \begin{macro}{\shortversion}\marg{options}\AfterLastParam A short, one-line version. In addition to the options specified in table~\ref{opt:version}, the following options are available for \cs{shortversion}: \begin{Optionlist} changes & The changes to display for this version \\ \end{Optionlist} \end{macro} \subsection{Helper commands} The \cl\ package defines several ``helper commands,'' which are colorized if the \option{color} package option has been given. See section~\ref{sec:colors} for more information. These commands introduce a \textit{set} of changes within the version. There must be at least one \cs{item} between one of these commands and the end of the \env{version} environment. \begin{macro}{\added}Introduces a list of \cs{item}s that represent added features\end{macro} \begin{macro}{\changed}Introduces a list of \cs{item}s that represent changed features\end{macro} \begin{macro}{\deprecated}Introduces a list of \cs{item}s that represent deprecated features\end{macro} \begin{macro}{\removed}Introduces a list of \cs{item}s that represent features which have been removed\end{macro} \begin{macro}{\fixed}Introduces a list of \cs{item}s that represent bug fixes\end{macro} \begin{macro}{\security}Introduces a list of \cs{item}s that represent security-fixes and closed security holes\end{macro} \subsection{Customization} The \env{changelog} environment wraps \env{changelogdescription} (which is defined by default to be just the \env{description} environment), and the \env{version} environment wraps \env{changelogitemize}. One could customize these in depth with \ctan{enumitem}, as in: \begin{latexcode} \usepackage{enumitem} \renewenvironment{changelogitemize} {\begin{itemize}[label=---]} {\end{itemize}} \end{latexcode} \begin{macro}{\changelogyanked} Prints the ``revoked release'' notice: \changelogyanked. See: \href{https://keepachangelog.com/en/1.0.0/#yanked}{yanked releases on \texttt{keepachangelog.com}}. \end{macro} \subsection{Colors}% \label{sec:colors} Colored output is supported by \ctan{xcolor}, which defines several named colors (as seen in figure~\ref{fig:colors}); these colors may be redefined as needed. While the \ctan{xcolor} documentation goes into great detail, you'll likely do fine with just e.g.\ \cs{colorlet}|{ChangelogAdded}{magenta}|. \begin{figure}[h] \centering \begin{adjustwidth}{1in}{1in} \begin{colorlist} \item{ChangelogAdded} \item{ChangelogChanged} \item{ChangelogDeprecated} \item{ChangelogRemoved} \item{ChangelogFixed} \item{ChangelogSecurity} \end{colorlist} \end{adjustwidth} \caption{Colors provided by the \cl\ package} \label{fig:colors} \end{figure} \subsubsection{Package options} \begin{Optionlist} color & Makes output more colorful; this is probably not that useful \end{Optionlist} \section{Changelog} This is this package's actual changelog --- not an example! \begin{changelog}[author=Rebecca Turner, section=false] \begin{version}[v=1.0.0, date=2018-12-28] \added \item The ``simple'' option for changelogs which aren't split up into sections of added, changed, removed, etc.\ features \changed \item Instead of commands like \cs{added} introducing an item, they introduce a list of items; this is what \keepachangelog\ actually intended; previous implementations were incorrect to display an ``Added'' (or whatever) marker next to each item. \end{version} \shortversion{v=0.2.1, date=2018-10-26, changes=Documented \option{yanked} option} \shortversion{v=0.2.0, date=2018-10-26, changes=First stable release} \shortversion{v=0.1.0, date=2018-10-25, changes=Initial beta} \end{changelog} \PrintIndex \listoftables \end{document}