% Created 2024-09-27 Fri 11:44
% Intended LaTeX compiler: pdflatex
\documentclass[11pt]{article}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\usepackage{graphicx}
\usepackage{longtable}
\usepackage{wrapfig}
\usepackage{rotating}
\usepackage[normalem]{ulem}
\usepackage{amsmath}
\usepackage{amssymb}
\usepackage{capt-of}
\usepackage{hyperref}
\usepackage{color}
\usepackage{listings}
\usepackage[margin=1.0in]{geometry}
\author{Brett Viren}
\date{\today{} (Draft v0.2)}
\title{DUNE Collaboration GitHub Organization Policy and Procedures}
\hypersetup{
 pdfauthor={Brett Viren},
 pdftitle={DUNE Collaboration GitHub Organization Policy and Procedures},
 pdfkeywords={},
 pdfsubject={},
 pdfcreator={Emacs 28.2 (Org mode 9.7-pre)}, 
 pdflang={English}}
\begin{document}

\maketitle
\tableofcontents

\section{Introduction}
\label{sec:org5b87add}

This document describes the policy and procedures related to the DUNE GitHub organization.  The DUNE collaboration, institutions and individual collaborators may utilize other GitHub organizations which are not necessarily subjects of this document.


\pagebreak
\section{Definitions}
\label{sec:org73fb866}

This policy and procedures sections below utilizes RFC 2119 key words (shall, may, etc) and adopts the following terms from or based on those defined in the GitHub taxonomy:

\begin{description}
\item[{organization (org)}] specifically the DUNE GitHub organization located at \url{https://github.com/DUNE}.

\item[{repository (repo)}] one of the informational sub units of the org as listed at \url{https://github.com/DUNE/repositories}.  This term here specifically excludes any git repositories which may be cloned or forked outside of this location.

\item[{account}] a record keeping unit in GitHub permission model.  An individual is an \textbf{account owner} if no other individual may use the account.

\item[{member}] a GitHub \textbf{account} associated with the org as listed at \url{https://github.com/orgs/DUNE/people}

\item[{organizer}] a \textbf{member} with org-level permission \texttt{role:owner} as listed at \url{https://github.com/orgs/DUNE/people?query=role\%3Aowner}

\item[{collaborator}] an individual associated with the DUNE collaboration as identified by the information the CollDb located at \url{https://dbweb8.fnal.gov:8443/CollDb/dune/Users/index}.   For the purpose of this document, all rows identify a collaborator and specifically the values in the ``COLLABORATOR'' column are not considered.

\item[{authority}] a collaborator that may direct an organizer to take action against any member or repository.

\item[{team}] a group of \textbf{members} with associated \textbf{repos} and set of variant permissions.

\item[{read}] permission and ability to view, clone, download a repo (be it public or private).

\item[{write}] permission and ability to make changes to a repo be that done via \texttt{git} or GitHub web interfaces.

\item[{admin}] permission and ability to perform additional actions on a repo or team.
\end{description}

\pagebreak
\section{Policy}
\label{sec:org411b347}

This section describes the DUNE GitHub organization policy. 
\subsection{Membership}
\label{sec:org19d1e51}

\begin{itemize}
\item A member must be owned by collaborator.

\item A collaborator may own a member account.

\item A member may make membership public. (Find entry at \url{https://github.com/orgs/DUNE/people} and toggle Public/Private).

\item An organizer shall grant and revoke membership.

\item A repo shall only be created by a member.

\item Only a member may write to a repo.

\item A repo should have at least one member designated as its admin.

\item Deletion or transfer of a repo shall only be performed by a repo admin or an organizer.

\item A team may be used to group members and repos in order to apply variant permissions.
\end{itemize}
\subsection{Contents}
\label{sec:org0d1b003}

\begin{itemize}
\item A repo should be public.

\item The contents of a repo shall be subject to the DUNE Software Copyright and Licensing Policy (DocDB 27141).

\item All contents must abide by the DUNE Code of Conduct.
\end{itemize}
\subsection{Non-member}
\label{sec:orgc28d82e}

\begin{itemize}
\item A non-member may read a public repo.

\item A non-member shall not read a private repo.

\item A non-member shall not directly write to a repo.

\item A non-member may indirectly write to a repo via a member.  

\begin{itemize}
\item A non-member should fork the repo and make a pull request (PR) to the original DUNE repo.  Only a member may merge the PR.

\item A non-member may provide contribution directly to a member.  Only a member may write the contribution to the original DUNE repo.
\end{itemize}

\item A member must review any contribution from a non-member.
\end{itemize}
\subsection{Permissions}
\label{sec:org919ba2a}

\begin{itemize}
\item To the extent possible, policy shall be reflected in settings provided by GitHub.
\end{itemize}
\subsection{Organizers}
\label{sec:orgab67496}

\begin{itemize}
\item DUNE collaboration shall assure at least three organizers.

\item The individuals serving as organizers shall not work for a single institution.

\item Membership in the set of organizers has no fixed term and may be modified at any time by a majority of the set of authorities.

\item An individual serving as organizer must have familiarity needed to perform tasks assigned to the role.
\end{itemize}
\subsection{Authority}
\label{sec:orge11f072}

\begin{itemize}
\item The set of authorities consists of two DUNE collaboration co-spokespeople and the lead of the DUNE Computing consortium. \emph{(Is this an appropriate set?  Set cardinality should allow for a meaningful majority decision in case of conflict so at least three people?)}

\item An authority may request the organizer to change permissions, remove membership, disband teams, remove repos or other actions enabled by organizer permissions that are not explicitly listed.

\item An organizer may execute an authority request with no delay.

\item An organizer may defer processing an authority request until requesting confirmation from all authorities and receiving confirmation from a simple majority of authorities.

\item An organizer shall enact a request that receives majority agreement with no delay.
\end{itemize}


\pagebreak
\section{Procedures}
\label{sec:org4e0b4dc}

This section describes the procedures for managing and using the DUNE GitHub organization.
\subsection{Requesting membership}
\label{sec:org00ad287}

\begin{itemize}
\item An applicant shall request membership from an organizer.

\item A request must include the name of the applying collaborator and the GitHub account.

\item The applicant should make the request via DUNE Slack channel \texttt{github-janitors}

\item The applicant may make the request via DUNE Slack private message to an organizer.

\item An application made via DUNE Slack shall be considered valid.

\item The applicant may make the request via email to an organizer.

\item An email request shall only be accepted after the following validation:
\begin{itemize}
\item The organizer matches the applicant given name in CollDb.
\item The organizer sends an email message to the matched email address.
\item The reply to that message is received with confirmation that the application was made.
\end{itemize}
\end{itemize}
\subsection{Membership removal}
\label{sec:org1f7ad63}

\begin{itemize}
\item Membership shall be removed upon loss of collaborator status.

\begin{itemize}
\item \emph{note: how to perform this task efficiently needs thought and effort}
\end{itemize}

\item Membership shall be removed according to the policy for requests from authorities.

\item Membership may be removed upon request by the member.

\item Removal requests shall be subject to the same validation procedure as membership requests.
\end{itemize}
\subsection{Creating repositories}
\label{sec:orgbb29cec}

\begin{itemize}
\item \emph{tbd. mostly some ``should'' guidelines, I'd imagine}
\end{itemize}
\subsection{Authority requests}
\label{sec:org3be4578}

\begin{itemize}
\item An authority makes an authority request to an organizer via the same channels as membership requests.

\item The organizer may enact the request immediately or delay to receive majority authority agreement.
\end{itemize}
\end{document}
