diff --git a/0_abstract.tex b/0_abstract.tex index dac2e0a..c3630cc 100644 --- a/0_abstract.tex +++ b/0_abstract.tex @@ -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. } diff --git a/1_introduction.tex b/1_introduction.tex index 02d2be6..74ad8c5 100644 --- a/1_introduction.tex +++ b/1_introduction.tex @@ -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 diff --git a/2_background.tex b/2_background.tex index 5059d71..1a59ebc 100644 --- a/2_background.tex +++ b/2_background.tex @@ -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 diff --git a/4_1.tex b/4_1.tex index f3ab003..954a3ce 100644 --- a/4_1.tex +++ b/4_1.tex @@ -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 diff --git a/4_4.tex b/4_4.tex index c289ba3..ed42650 100644 --- a/4_4.tex +++ b/4_4.tex @@ -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} \ No newline at end of file diff --git a/6_conlusion.tex b/6_conlusion.tex index ce78da4..f52c13c 100644 --- a/6_conlusion.tex +++ b/6_conlusion.tex @@ -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 diff --git a/9_ref.bib b/9_ref.bib index 2bbfbe6..188cfb1 100644 --- a/9_ref.bib +++ b/9_ref.bib @@ -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}, diff --git a/experiment_code/1-popularity/overvie.py b/experiment_code/1-popularity/overvie.py index adda005..1f2fe07 100644 --- a/experiment_code/1-popularity/overvie.py +++ b/experiment_code/1-popularity/overvie.py @@ -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() diff --git a/scis_paper.tex b/scis_paper.tex index 3165721..6cf7814 100755 --- a/scis_paper.tex +++ b/scis_paper.tex @@ -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: ͨ������ @@ -82,7 +82,7 @@ %%% Address. ��ַ %%% \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}