193 lines
9.9 KiB
TeX
193 lines
9.9 KiB
TeX
\subsection{RQ2: Documentation Maintenance}
|
|
|
|
We investigated the maintenance practice of community profile documentation from multiple aspects,
|
|
including location, creation latency, maintainers, update frequency and change-triggering events.
|
|
The followings report each of the investigation in detail.
|
|
|
|
\subsubsection{Documentation location}
|
|
As discussed in Section~\ref{iden},
|
|
GitHub developers are recommended to place the
|
|
community profile documentation in one of the three directories,
|
|
\ie \textit{tree}, \textit{docs}, and \textit{.github}.
|
|
Table~\ref{tab:org_loc} presents the distribution of locations for each type of documentation in the studied projectors.
|
|
Note that the total frequency of some documentation might be more than 100\%
|
|
since some projects place duplicates of the documentation in multiple locations.
|
|
|
|
Generally speaking,
|
|
the \RDM, \LIC, and \CON documentation is mainly placed in the \textit{root} directory,
|
|
and the \TMP documentation is mainly placed in the \textit{.github} directory.
|
|
Only a very few documentation is placed in the \textit{docs} directory.
|
|
Placing a community document in the \textit{root} directory increases its chance to be noticed by contributors.
|
|
Especially,
|
|
because \RDM files are the first document that developers see
|
|
when they explore a project in GitHub~\cite{Prana2018Categorizing},
|
|
adding links to other documentation in the \RDM files is a recommended practice to
|
|
make community documentation more observable.
|
|
For the \TMP documentation,
|
|
it does not need to be read through manually by the contributors.
|
|
Instead,
|
|
it is used by GitHub to automatically remind the contributors of
|
|
the required information or suggestions
|
|
when they are opening an issue or a pull request.
|
|
Therefore,
|
|
placing \TMP files in the hidden \textit{.github} directory is useful to keep the \textit{root} directory clean.
|
|
|
|
|
|
\begin{table}[ht!]
|
|
\centering
|
|
\caption{The distribution of locations of each kind of documentation}
|
|
\begin{tabular}{@{}r c c c c c@{}}
|
|
\bottomrule
|
|
\textbf{Location} &\textbf{\footnotesize\RDM} & \textbf{\footnotesize\LIC} &\textbf{\footnotesize\CON} & \textbf{\footnotesize\COD} & \textbf{\footnotesize\TMP}\\
|
|
\midrule
|
|
\textit{root} & 1.00\%& 1.00\%& 0.83\%& 0.86\%& 0.12\%\\
|
|
\textit{docs} & 0.05\%& 0.01\%& 0.06\%& 0.02\%& 0.01\%\\
|
|
\textit{.github} & 0.00\%& 0.00\%& 0.13\%& 0.12\%& 0.89\%\\
|
|
\toprule
|
|
\end{tabular}
|
|
\label{tab:org_loc}
|
|
\end{table}
|
|
|
|
|
|
\subsubsection{Creation}
|
|
We investigated the creation time of community profile documentation,
|
|
\ie how long it takes to include the documentation after the project creation.
|
|
In each studied project,
|
|
for each type of profile documentation,
|
|
we went through all the projects,
|
|
and computed the latency between the project's creation time and the documentation's creation time, if it was found in the project.
|
|
Figure~\ref{fig:main_creat} shows the distribution of creation latency for all five types of documentation in the studied projectors.
|
|
Comparatively,
|
|
the \RDM and \LIC documentation is included earlier than the \CON, \COD, and \TMP documentation.
|
|
On average,
|
|
\RDM and \LIC files are included 366.76 (median: 17.08) days and 248.18 (median: 0.78) days after the project is created, respectively,
|
|
while \CON, \COD, and \TMP files are included 654.45 (median: 317.11) days, 773.55 (median: 379.92) day, and 865.50 (median: 624.82) days after the project creation, respectively.
|
|
The short creation latency of the \RDM and \LIC documentation might be due to that
|
|
a proportion of repositories create these two files
|
|
at the launch time, as shown in Figure~\ref{fig:new_repo}.
|
|
|
|
|
|
|
|
\begin{figure}[ht!]
|
|
\centering
|
|
\includegraphics[width=0.9\textwidth]{resources/creation.pdf}
|
|
\caption{The distribution of creation latency of documentation (the horizontal line in each violin plot indicates the median value).}
|
|
\label{fig:main_creat}
|
|
\end{figure}
|
|
|
|
|
|
|
|
\subsubsection{Update frequency}
|
|
\label{interval}
|
|
|
|
We explored how frequent is community profile documentation updated.
|
|
For each document,
|
|
we compute the intervals between every two adjacent commits.
|
|
The smaller the interval,
|
|
the more frequently the document is updated.
|
|
Figure~\ref{fig:main_interval} presents
|
|
the distribution of update interval for each kind of documentation in the studied projects.
|
|
The update interval (in day) of the \RDM, \LIC, \CON, \COD and \TMP documentation
|
|
is 44.42 (median: 3.75), 333.72 (median: 169.57), 99.39 (median: 18.54), 205.92 (median: 48.92), and 116.29 (median: 25.16), respectively.
|
|
We can note that \RDM files are updated more frequently than other files.
|
|
There are two possible explanations.
|
|
First,
|
|
\RDM files have higher chances to be read by community developers as the homepage of a project,
|
|
and therefore the defects in \RDM files are more likely to be fixed.
|
|
Second,
|
|
the \RDM files are used to present the various information about the project~\cite{Prana2018Categorizing}
|
|
(\eg configuration and versions),
|
|
and therefore they need to be frequently updated as the project evolves.
|
|
|
|
|
|
|
|
\begin{figure}[ht!]
|
|
\centering
|
|
\includegraphics[width=0.9\textwidth]{resources/interval.pdf}
|
|
\caption{The distribution of update interval of documentation}
|
|
\label{fig:main_interval}
|
|
\end{figure}
|
|
|
|
|
|
\subsubsection{Maintainers}
|
|
|
|
We consider the author of each commit that changes the community profile documentation
|
|
as a maintainer of the documentation.
|
|
For each profile document in a project,
|
|
we got all the commits on it and counted the number of different maintainers (\ie commit authors) of the document.
|
|
Table~\ref{fig:main_matner} presents the distribution of maintainers for each type of documentation in the studied projectors.
|
|
Overall,
|
|
community profile documentation is usually maintained by a relatively small group of developers,
|
|
which is in line with the finding in a previous survey
|
|
that 60 percent of survey respondents rarely or never contributed to documentation~\cite{GitHubOpenSourceSurvey2017}.
|
|
More specifically,
|
|
the numbers of maintainers of the \LIC, \CON, \COD and \TMP documentation
|
|
are 1.31 (median: 1), 2.52 (median: 1), 1.27 (median: 1), and 1.79 (median: 1), respectively.
|
|
Exceptionally,
|
|
\RDM files are maintained by more developers than other kinds of documentation;
|
|
the average number of its maintainers is 4.84 (median: 3).
|
|
This is might be explained by the same reasons for the high update frequency of \RDM files
|
|
as shown in Section~\ref{interval}.
|
|
|
|
\begin{figure}[ht!]
|
|
\centering
|
|
\includegraphics[width=0.9\textwidth]{resources/maintainers.pdf}
|
|
\caption{The distribution of maintainers of community profile documentation.}
|
|
\label{fig:main_matner}
|
|
\end{figure}
|
|
|
|
|
|
|
|
|
|
\subsubsection{Change triggers}
|
|
|
|
|
|
We would like to investigate what events can trigger the change of community profile documentation.
|
|
To this end,
|
|
for each kind of profile document,
|
|
we collected all the commit messages and
|
|
computed the occurrence frequency of keywords extracted from the messages after tokenization, removing stop words and stemming.
|
|
Table~\ref{tab:main_trigger} lists the top-20 keywords with higher frequency for each kind of documentation.
|
|
In order to interpret which kind of change type a specific keyword tend to represent,
|
|
we follow the guidelines from prior studies~\cite{mockus2000identifying,hassan2009predicting}.
|
|
Overall,
|
|
the update of community profile documentation is mainly driven by
|
|
\textit{perfective changes} (\eg ``add'' and ``creat[e]'') and \textit{adaptive changes} (\eg ``updat[e]'' and ``remov[e]'' ) more than \textit{corrective changes} (\eg ``fix'' and ``error'').
|
|
We can also observe interesting keywords in some documentation's commit messages.
|
|
For example,
|
|
the keyword ``link'' occurs frequently in the update events of the \RDM, \CON, and \TMP documentation,
|
|
which means that the links contained in the three kinds of documents need to be often changed (added, modified or deleted).
|
|
Additionally,
|
|
\LIC files and \RDM files are changed frequently to update the copyright ``year'', ``version'' and
|
|
the ``badg[e]''~\cite{2018Adding}.
|
|
|
|
|
|
\begin{table}[ht!]
|
|
\centering
|
|
\caption{The most frequent keywords contained in commit messages}
|
|
\begin{tabular}{@{}r p{12cm}@{}}
|
|
\bottomrule
|
|
\textbf{Documentation}&\textbf{Keyword list}\\ \hline
|
|
\textbf{\RDM} & updat, add, fix, doc, link, remov, version, use, chang, badg, test, support, releas, document, new, build, exampl, merg, typo, instal
|
|
% ,com, sign, ci, improv, option, bump, section, branch, instruct, make
|
|
\\ \hline
|
|
\textbf{\LIC} & updat, add, initi, fix, year, creat, chang, version, php, file, mit, remov, use, id, test, new, first, releas, svn, licens, project, git, apach, renam, move, http, doc, notic, sourc\\ \hline
|
|
\textbf{\CON} & add, updat, fix, doc, test, remov, use, link, chang, github, issu, new, move, guid, document, build, sign, make, version, file, error, guidelin, ci, contribut, com, templat, expo, creat, releas, run\\ \hline
|
|
\textbf{\COD} & add, fix, updat, remov, test, error, use, doc, creat, conduct, import, order, chang, product, set, function, issu, method, compon, name, tax, move, new, item, file, invoic, log, default, field\\ \hline
|
|
\textbf{\TMP} & gatsbi, templat, add, updat, issu, plugin, fix, pr, github, doc, pull, alpha, request, issue\_templ, sourc, link, remov, use, pull\_request\_templ, chang, transform, test, remark, creat\\ \hline
|
|
\toprule
|
|
\multicolumn{2}{l}{\textit{Note: the keywords are presented in the stemmed formate, e.g., ``updat'' indicates ``update''}}
|
|
\end{tabular}
|
|
\label{tab:main_trigger}
|
|
\end{table}
|
|
|
|
|
|
\begin{framed}
|
|
\noindent\textbf{RQ2:}
|
|
Except for the \TMP documentation which is mostly placed in the \textit{.github} directory,
|
|
community profile documentation is mainly placed in the \textit{root} directory.
|
|
The \RDM and \LIC documentation is usually included earlier than the \CON, \COD, and \TMP documentation.
|
|
Community profile documentation is usually maintained by a small group of developers with a low frequency of update.
|
|
And the updates are mainly driven by perfective and adaptive changes more than corrective changes.
|
|
\end{framed}
|
|
|