%% Generated by Sphinx.
\def\sphinxdocclass{report}
\documentclass[letterpaper,10pt,english]{sphinxmanual}
\ifdefined\pdfpxdimen
   \let\sphinxpxdimen\pdfpxdimen\else\newdimen\sphinxpxdimen
\fi \sphinxpxdimen=.75bp\relax

\PassOptionsToPackage{warn}{textcomp}
\usepackage[utf8]{inputenc}
\ifdefined\DeclareUnicodeCharacter
% support both utf8 and utf8x syntaxes
\edef\sphinxdqmaybe{\ifdefined\DeclareUnicodeCharacterAsOptional\string"\fi}
  \DeclareUnicodeCharacter{\sphinxdqmaybe00A0}{\nobreakspace}
  \DeclareUnicodeCharacter{\sphinxdqmaybe2500}{\sphinxunichar{2500}}
  \DeclareUnicodeCharacter{\sphinxdqmaybe2502}{\sphinxunichar{2502}}
  \DeclareUnicodeCharacter{\sphinxdqmaybe2514}{\sphinxunichar{2514}}
  \DeclareUnicodeCharacter{\sphinxdqmaybe251C}{\sphinxunichar{251C}}
  \DeclareUnicodeCharacter{\sphinxdqmaybe2572}{\textbackslash}
\fi
\usepackage{cmap}
\usepackage[T1]{fontenc}
\usepackage{amsmath,amssymb,amstext}
\usepackage{babel}
\usepackage{times}
\usepackage[Bjarne]{fncychap}
\usepackage{sphinx}

\fvset{fontsize=\small}
\usepackage{geometry}

% Include hyperref last.
\usepackage{hyperref}
% Fix anchor placement for figures with captions.
\usepackage{hypcap}% it must be loaded after hyperref.
% Set up styles of URL: it should be placed after hyperref.
\urlstyle{same}
\addto\captionsenglish{\renewcommand{\contentsname}{Contents:}}

\addto\captionsenglish{\renewcommand{\figurename}{Fig.\@ }}
\makeatletter
\def\fnum@figure{\figurename\thefigure{}}
\makeatother
\addto\captionsenglish{\renewcommand{\tablename}{Table }}
\makeatletter
\def\fnum@table{\tablename\thetable{}}
\makeatother
\addto\captionsenglish{\renewcommand{\literalblockname}{Listing}}

\addto\captionsenglish{\renewcommand{\literalblockcontinuedname}{continued from previous page}}
\addto\captionsenglish{\renewcommand{\literalblockcontinuesname}{continues on next page}}
\addto\captionsenglish{\renewcommand{\sphinxnonalphabeticalgroupname}{Non-alphabetical}}
\addto\captionsenglish{\renewcommand{\sphinxsymbolsname}{Symbols}}
\addto\captionsenglish{\renewcommand{\sphinxnumbersname}{Numbers}}

\addto\extrasenglish{\def\pageautorefname{page}}

\setcounter{tocdepth}{1}



\title{Librem 5 Development Policy Documentation}
\date{Dec 04, 2019}
\release{0}
\author{Guido Günther}
\newcommand{\sphinxlogo}{\vbox{}}
\renewcommand{\releasename}{Release}
\makeindex
\begin{document}

\pagestyle{empty}
\sphinxmaketitle
\pagestyle{plain}
\sphinxtableofcontents
\pagestyle{normal}
\phantomsection\label{\detokenize{index::doc}}



\chapter{Introduction}
\label{\detokenize{intro:introduction}}\label{\detokenize{intro::doc}}
This document desribes the policy requirements for the Librem 5. It’s
purpose is to reflect current practice for developing on the Librem 5.
It’s uses the wording from \sphinxhref{https://tools.ietf.org/html/rfc2119}{rfc2119}.


\chapter{Software}
\label{\detokenize{software:software}}\label{\detokenize{software::doc}}
General policy for software we build and distribute:
\begin{enumerate}
\def\theenumi{\arabic{enumi}}
\def\labelenumi{\theenumi .}
\makeatletter\def\p@enumii{\p@enumi \theenumi .}\makeatother
\setcounter{enumi}{-1}
\item {} 
All source code should be maintained in a public git repository in
the \sphinxstyleemphasis{Librem5} space on \sphinxurl{https://source.puri.sm}.

\item {} 
All developed software must conform to a OSI compatible license.

\item {} 
For software where we’re upstream the \sphinxhref{https://www.gnu.org/licenses/gpl-3.0.en.html}{GPLv3} should beused for
programs while the \sphinxhref{https://www.gnu.org/licenses/lgpl-3.0.en.html}{LGPLv3} should be used
for libraries.

\item {} 
If we’re not upstream, upstream’s license should be used.

\item {} 
We must not require a Contributor License Agreement  (CLA).

\item {} 
The projects should use a \sphinxhref{https://developercertificate.org/}{Developer Certificate of Origin} (DCO).

\end{enumerate}


\chapter{Git(lab) Repository}
\label{\detokenize{git:git-lab-repository}}\label{\detokenize{git::doc}}
Policy regarding git repository layout and configuration. This applies
to repositories in the \sphinxstyleemphasis{Librem5} space on \sphinxurl{https://source.puri.sm}:
\begin{enumerate}
\def\theenumi{\arabic{enumi}}
\def\labelenumi{\theenumi .}
\makeatletter\def\p@enumii{\p@enumi \theenumi .}\makeatother
\setcounter{enumi}{-1}
\item {} 
The default branch of the repository must be the branch where people
should contribute to if they want to advance development.
It must not be an outdated, unused branch or the master branch of
the upstream repository if we maintain a downstream fork.

\item {} 
Canonical branch naming should be used. If we’re upstream the main
development branch should be called \sphinxstyleemphasis{master}, if we’re maintaing a
phone specific fork of a software, the branch should be called
\sphinxstyleemphasis{librem5}. These branches must be \sphinxhref{https://docs.gitlab.com/ee/user/project/protected\_branches.html}{protected branches}
that don’t allow force pushes.

\item {} 
The description in Gitlab must describe the repositories
purpose. If it’s a mirror from somewhere else this must be
mentioned. If it’s no longer maintained too.

\item {} 
The repository should have a \sphinxtitleref{README.md} that tells people where to
report bugs (which is the minimal entry point to interact with the
maintainers). Other channels like irc, matrix, mailing lists should
also be mentioned there.

\item {} 
Each repository should have a \sphinxhref{https://en.wikipedia.org/wiki/DOAP}{doap} file that documents the
current maintainers.

\item {} 
Contributions should happen via merge requests in Gitlab to allow
for code review and automated testing. Direct pushes should be
avoided.

\item {} 
Merge request should happen from a personal fork of the repository
not from branches within the repository.

\item {} 
The repository should have a \sphinxstyleemphasis{.gitignore} file that sets up git
to ignore generated artifacts. The aim is that after a build
the repositories status is still clean.

\end{enumerate}


\chapter{Gitlab CI}
\label{\detokenize{ci:gitlab-ci}}\label{\detokenize{ci::doc}}\begin{enumerate}
\def\theenumi{\arabic{enumi}}
\def\labelenumi{\theenumi .}
\makeatletter\def\p@enumii{\p@enumi \theenumi .}\makeatother
\setcounter{enumi}{-1}
\item {} 
Each repository should have a Gitlab CI configuration. For software
where we’re upstream it should be stored in \sphinxstyleemphasis{./.gitlab-ci.yml} in
the git repository. This configuration must at least build the
artifacts (binaries, documentation) and should run the unit tests
that don’t require any special setup.

\item {} 
The CI pipeline of each repository should be green since everything else
drives possible contributors away and makes it harder for
contributors to evaluate the impact their changes. Temporary breackage
will happen but it should not be the norm.

\item {} 
The CI pipeline should produce artifacts for easy consumption. A Debian
package is a must for system components. Applications should produce
a flatpak.

\item {} 
The CI should run against multiple platforms. E.g. prepare for the
future by building/testing against Debian testing as well.

\end{enumerate}


\chapter{Development}
\label{\detokenize{development:development}}\label{\detokenize{development::doc}}\begin{enumerate}
\def\theenumi{\arabic{enumi}}
\def\labelenumi{\theenumi .}
\makeatletter\def\p@enumii{\p@enumi \theenumi .}\makeatother
\item {} 
Allow for short build, test cycles. Software that needs lots of
manual commands to run is annoying for contributors.

\item {} 
Being able to run directly from the source tree should be possible
so contributors don’t need to clutter their systems for smoke
testing. If things need special setup provide a \sphinxstyleemphasis{run} script that
performs that. This does imply that \sphinxstyleemphasis{every} aspect of the software
is testable that way.

\item {} 
Since the project is GNOME based \sphinxhref{https://www.gtk.org/}{GTK}
should be used as GUI toolkit.

\item {} 
Developed libraries should be \sphinxhref{https://wiki.gnome.org/Projects/GObjectIntrospection}{GObject introspectable} to ease
use from other programming languages.

\item {} 
Applications should follow the \sphinxhref{https://developer.gnome.org/hig/}{GNOME Hig}.

\end{enumerate}


\chapter{Debian Packaging}
\label{\detokenize{debian_packaging:debian-packaging}}\label{\detokenize{debian_packaging::doc}}
This chapter documents Debian packaging policy. It only applies to
packages building at least one Debian package.
\begin{enumerate}
\def\theenumi{\arabic{enumi}}
\def\labelenumi{\theenumi .}
\makeatletter\def\p@enumii{\p@enumi \theenumi .}\makeatother
\setcounter{enumi}{-1}
\item {} 
\sphinxhref{https://www.debian.org/doc/debian-policy/}{Debian policy} should be followed,
preferably version 4.4.0 or later.

\item {} 
\sphinxtitleref{debian/README.source} should contain instructions if there are
special steps required to import new upstream sources or to build
the package

\item {} 
If you’re modifiying / backporting non-native Debian packages you
should use \sphinxhref{https://manpages.debian.org/stretch/pristine-tar/pristine-tar.1.en.html}{pristine-tar}
and a \sphinxstyleemphasis{pristine-tar} branch. This will make sure the build systems
are able to reproduce a bit identical upstream tarball from the git
repository.

\end{enumerate}


\chapter{Indices and tables}
\label{\detokenize{index:indices-and-tables}}\begin{itemize}
\item {} 
\DUrole{xref,std,std-ref}{genindex}

\item {} 
\DUrole{xref,std,std-ref}{modindex}

\item {} 
\DUrole{xref,std,std-ref}{search}

\end{itemize}



\renewcommand{\indexname}{Index}
\printindex
\end{document}