starlee
/
prj_doc
0
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

minor changes

This commit is contained in:
whystar 2020-09-06 16:07:54 +08:00
parent f67fd526bd
commit 6ae2e31bc3
9 changed files with 42 additions and 33 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
0_abstract.tex
View File

@ -13,13 +13,13 @@ We randomly collected 2,000 OSS projects from GitHub,
based on which
we studied the documentation popularity by programming language, repository owner type, repository age, and community size, respectively.
We also investigated the maintenance practice of community profile documentation in terms of
location, creation latency, maintainers, update interval and change-triggering events, respectively.
location, creation latency, maintainers, update frequency and change-triggering events, respectively.
\textbf{Results:}
\RDM, and \LIC documentation is far more popular and created earlier than \CON, \COD and \TMP documentation in GitHub OSS projects.
The \RDM, and \LIC documentation is far more popular and created earlier than the \CON, \COD and \TMP documentation in GitHub OSS projects.
Community profile documentation is more likely to be found in
repositories of TypeScript, repositories of larger community size, and repositories owned by organizations.
% \RDM and \LIC documentation is created earlier than \CON, \COD, and \TMP documentation.
It is mainly placed in the \textit{root} directory and changed by a small group of developers with a low frequency of update,
Community profile documentation is mainly placed in the \textit{root} directory and changed by a small group of developers with a low frequency of update,
which is mostly driven by
perfective and adaptive requirements.
}

26
1_introduction.tex
View File

@ -1,13 +1,12 @@
\section{Introduction}
%
Documentation plays an important role in open source software (OSS).
For example,
API references~\cite{Zhong2009Inferring, Treude2016Augmenting} tell developers about what they can do and how they should do with the software,
and tutorials~\cite{jiang2017an} assist developers to get familiar with the software using contextualized examples.
For community-based OSS projects
that are relying on developers from all around the world,
there is one kind of important documentation, \ie \textit{community profile documentation},
there is one kind of crucial documentation, \ie \textit{community profile documentation},
which can help project maintainers to \textit{``grow their community and support contributors''}, and help contributors to \textit{``see if they want to contribute to the project''}~\footnote{\url{https://docs.github.com/en/github/building-a-strong-community/about-community-profiles-for-public-repositories}}.
@ -18,7 +17,8 @@ which attracts more than 40 million of developers~\cite{github},
has been the most popular platform for community-based OSS development
because of its social coding support~\cite{Dabbish2012Social,storey2016social} and pull-based collaborating mechanism~\cite{Zhu2016Effe,jiang2017and}.
In GitHub specifically,
project maintainers can include five main kinds of community profile documentation.
there are five different kinds of community profile documentation,
which play a variety of roles.
When users create a new repository,
they have a chance to decide whether to initialize it with a default \RDM file and whether to add a \LIC file from a list of candidates.
A \RDM file is used as the homepage of a project in GitHub,
@ -31,12 +31,12 @@ who freely and volunteerly contribute to interested projects.
% the maintainers need to continuously recruit and retain newcomers.
Therefore,
a \CON file,
which specifies the recommended contributing standards and processes in a project,
which specifies the expected contributing standards and processes in a project,
can be created to facilitate the onboarding and participation of OSS developers~\cite{Steinmacher2016}.
A \COD file outlines the rules for communication between community participants,
which is helpful to establish a welcoming and friendly community~\cite{Tourani2017Code}.
In order to
remind contributors to report expected information when submitting issues and pull requests,
remind contributors to report necessary information when submitting issues and pull requests,
project maintainers can
include a \TMP file to customize and standardize issue and pull request description~\cite{template}.
@ -54,18 +54,20 @@ we studied how common each kind of community profile documentation is in the col
And more specifically,
we examined how the prevalence varies across different programming language, repository owner type, repository age, and community size, respectively.
To comprehensively reveal the maintenance practice of community profile documentation,
we explored the directory they are placed at,
the time they are added after the project creation,
the maintainers changing them
the frequency they are updated,
and the events triggering their changes.
Our findings present a quantitative insights into and achieve a better understanding of OSS community profile documentation.
we explored the directory it is placed at,
the time when it is added after the project creation,
the maintainers changing it,
and
the frequency and triggers of its changes.
% the frequency it is updated with,
% and the events triggering its changes.
Our findings present a quantitative insight into and achieve a better understanding of OSS community profile documentation.
The main contributions of the paper are as follows:
\begin{itemize}
\item Constructing a large scale of dataset~\footnote{The dataset will be made public upon acceptance of the paper.} of community profile documentation collected from 2,000 OSS projects randomly sampled from GitHub,
\item Constructing a large-scale dataset~\footnote{The dataset will be made public upon acceptance of the paper.} of community profile documentation collected from 2,000 OSS projects randomly sampled from GitHub,
which can be used in future research for other intentions.
\item Presenting the prevalence of community profile documentation from multiple perspectives,
which can help OSS contributors make more informed choices

7
2_background.tex
View File

@ -2,11 +2,6 @@
\label{sec:bg}
% Software Documentation Issues Unveiled
% Discovering community patterns in open-source: a systematic approach and its evaluation
% The Types, Roles, and Practices of Documentation in Data Analytics Open Source Software Libraries
% 把newcomer那个再展开一下
After years of development,
GitHub has synthesized various functionalities for OSS development,
such as hosting source code, tracking issues~\cite{bissyande2013got}, and submitting pull requests~\cite{Gousios:2014}.
@ -15,7 +10,7 @@ which makes GitHub be the main platform for community-based collaboration.
As aforementioned,
profile documentation is crucial for OSS communities to operate and survive.
However,
according to previous research in this area~\cite{Steinmacher2016,Gousios:2016,lee2017understanding},
according to previous research in this area~\cite{Steinmacher2016,Gousios:2016,lee2017understanding,GitHubOpenSourceSurvey2017},
one of the main challenges faced by OSS developers, especially the newcomers,
is the lack of or the low quality of such documentation.
To make it more clear about what content should be included in

6
4_1.tex
View File

@ -186,10 +186,10 @@ The average age (in month) of repositories including
the \RDM, \LIC, \CON, \COD, and \TMP documentation is
53.63 (median: 48.83), 53.17 (median: 48.62), 57.69 (median: 55.27), 47.46 (median: 42.20), and 53.62 (median: 47.75),
respectively.
While the average age of repositories not including the documentation is
While the average age of repositories not including such documentation is
92.48 (median: 105.44), 57.28 (median: 50.93), 52.60 (median: 46.77), 54.74 (median: 50.07), and 54.04 (median: 49.67), respectively.
We noted that
projects including a \RDM file, a \LIC file, a \COD file, or a \TMP are younger than those not including such a file,
projects including a \RDM file, a \LIC file, a \COD file, or a \TMP file are younger than those not including such a file,
and projects including a \CON file are older than those not including such a file.
The significance of difference between \textit{Included} and \textit{Not-included} was tested with Mann-Whitney-Wilcoxon test~\cite{Wilcoxon1945Individual}.
As shown in Table~\ref{tab:age_test},
@ -292,7 +292,7 @@ including the profile documentation might facilitate the collaboration between c
Overall,
the \RDM, and \LIC documentation is far more popular than the \CON, \COD and \TMP documentation in OSS projects.
Repositories of TypeScript are more inclined to include community profile documentation than repositories of other programming language.
Organizations have higher chances of adding the \CON, \COD, and \TMP documentation in their projects than personal users.
Organizations have higher chances of adding the \CON, \COD, and \TMP documentation in their repositories than personal users.
% Younger projects are more likely to include a \RDM file and a \COD file,
% but less likely to include a \CON file.
% The likelihood of including community profile documentation

8
4_4.tex
View File

@ -117,8 +117,10 @@ 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 was usually maintained by a relatively small group of developers.
Specifically,
community profile documentation was 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.
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,
@ -186,6 +188,6 @@ Except for the \TMP documentation which is mostly placed in the \textit{.github}
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 the updates are mainly driven by perfective and adaptive changes more than corrective changes.
And the updates are mainly driven by perfective and adaptive changes more than corrective changes.
\end{framed}

2
6_conlusion.tex
View File

@ -6,7 +6,7 @@
In this paper,
we quantitatively investigated the prevalence (RQ1) and maintenance (RQ2) of community profile documentation.
We studied on a sample of 2,000 OSS projects randomly collected from GitHub.
We conducted a large-scale study on 2,000 OSS projects randomly collected from GitHub.
Our analysis indicates that
the \RDM and \LIC documentation is far more pervasive
and included earlier

10
9_ref.bib
View File

@ -8,6 +8,16 @@
}
@misc{GitHubOpenSourceSurvey2017,
author = {Zlotnick, Frances},
title = {GitHub Open Source Survey 2017},
month = jun,
year = 2017,
doi = {10.5281/zenodo.806811},
publisher = {GitHub, Inc.},
howpublished = {\url{http://opensourcesurvey.org/2017/}}
}
@article{storey2016social,
title={How social and communication channels shape and challenge a participatory culture in software development},
author={Storey, Margaret-Anne and Zagalsky, Alexey and Figueira Filho, Fernando and Singer, Leif and German, Daniel M},

6
experiment_code/1-popularity/overvie.py
View File

@ -24,7 +24,7 @@ def profile_type(doc):
for fi in ["readme"]:
if doc_name.lower().find(fi) != -1:
return "readme"
for fi in ["license"]:
for fi in ["license","licence","copyright"]:
if doc_name.lower().find(fi) != -1:
return "license"
for fi in ["issue_template","pull_request_template"]:
@ -302,11 +302,11 @@ def by_forks():
if __name__ == "__main__":
# overview()
overview()
# by_language()
# by_role()
# by_age()
by_forks()
# by_forks()

4
scis_paper.tex
View File

@ -59,7 +59,7 @@
%%% \title{title}{title for citation}
\title{The Prevalence and Maintenance of OSS Community Profile Documentation: A Quantitative Perspective}{The Prevalence and Maintenance of OSS Community Profile Documentation: A Quantitative Perspective}
\title{The Prevalence and Maintenance of OSS Community Profile Documentation: A Quantitative View}{The Prevalence and Maintenance of OSS Community Profile Documentation: A Quantitative View}
% \title{The Prevalence and Maintenance of OSS Community Profile Documentation: A Quantitative View}{The Prevalence and Maintenance of OSS Community Profile Documentation: A Quantitative View}
%%% Corresponding author: ͨ<><CDA8><EFBFBD><EFBFBD><EFBFBD><EFBFBD>
@ -82,7 +82,7 @@
%%% Address. <20><>ַ
%%% \address[number]{Affiliation, City {\rm Postcode}, Country}
\address[1]{National Laboratory for Parallel and Distributed Processing}
\address[1]{Key Laboratory for Parallel and Distributed Processing, National University of Defense Technology, Changsha {\rm 410073}, China}
\address[2]{College of Computer, National University of Defense Technology, Changsha {\rm 410073}, China}