├── contributions.png ├── PLOS-submission.eps ├── .gitignore ├── submission-2019-04-12.txt ├── submission-2019-08-08.txt ├── Makefile ├── LICENSE.md ├── CITATION.cff ├── submission-2019-07-06.txt ├── submission-2019-07-10.txt ├── settings.tex ├── CODE_OF_CONDUCT.md ├── feedback-2019-06-04.txt ├── 10-newcomers.bib ├── README.md ├── 10-newcomers.tex └── plos2015.bst /contributions.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/gvwilson/10-newcomers/HEAD/contributions.png -------------------------------------------------------------------------------- /PLOS-submission.eps: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/gvwilson/10-newcomers/HEAD/PLOS-submission.eps -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | *.aux 2 | *.bbl 3 | *.blg 4 | *.log 5 | *.log 6 | *.out 7 | *.pdf 8 | *~ 9 | .DS_Store 10 | -------------------------------------------------------------------------------- /submission-2019-04-12.txt: -------------------------------------------------------------------------------- 1 | April 12, 2019 2 | 3 | To whom it may concern, 4 | 5 | Please find attached our paper "Ten Simple Rules for Helping Newcomers Become Contributors to Open Source Projects", which we wish to submit for publication. We hope you enjoy it, and look forward to hearing from you. 6 | 7 | Sincerely, 8 | 9 | Dan Sholler, Igor Steinmacher, Denae Ford, Mara Averick, Mike Hoye, and Greg Wilson 10 | 11 | gvwilson@third-bit.com 12 | -------------------------------------------------------------------------------- /submission-2019-08-08.txt: -------------------------------------------------------------------------------- 1 | 1. Reformatted authors' affiliations. 2 | - Please note that the link in the Word document to the example 404's. 3 | 4 | 2. I confirm that there was no funding for this work. 5 | 6 | 3. I have removed the Abstract and Author Summary. 7 | 8 | 4. I have moved the Acknowledgments to be just prior to the References. 9 | 10 | 5. We have turned the bullet list in Rule 1 into prose, but decided to leave the list in Rule 3 as-is. 11 | 12 | 6. The "figure" is text, so I have inlined it. 13 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | LATEX=pdflatex 2 | BIBTEX=bibtex 3 | STEM=10-newcomers 4 | 5 | all : commands 6 | 7 | ## commands : show all commands. 8 | commands : 9 | @grep -E '^##' Makefile | sed -e 's/## //g' 10 | 11 | ## pdf : re-generate PDF 12 | pdf : 13 | ${LATEX} ${STEM} 14 | ${BIBTEX} ${STEM} 15 | ${LATEX} ${STEM} 16 | ${LATEX} ${STEM} 17 | 18 | ## clean : clean up junk files. 19 | clean : 20 | @rm -rf _site 21 | @find . -name '*~' -exec rm {} \; 22 | @find . -name '*.aux' -exec rm {} \; 23 | @find . -name '*.bak' -exec rm {} \; 24 | @find . -name '*.bbl' -exec rm {} \; 25 | @find . -name '*.blg' -exec rm {} \; 26 | @find . -name '*.dvi' -exec rm {} \; 27 | @find . -name '*.log' -exec rm {} \; 28 | @find . -name '*.out' -exec rm {} \; 29 | @find . -name .DS_Store -exec rm {} \; 30 | -------------------------------------------------------------------------------- /LICENSE.md: -------------------------------------------------------------------------------- 1 | # License 2 | 3 | *This is a human-readable summary of (and not a substitute for) the license. 4 | Please see for the full legal text.* 5 | 6 | --- 7 | 8 | This work is licensed under the Creative Commons Attribution 4.0 9 | International license (CC-BY-4.0). 10 | 11 | **You are free to:** 12 | 13 | - **Share**---copy and redistribute the material in any medium or 14 | format 15 | 16 | - **Remix**---remix, transform, and build upon the material for any 17 | purpose, even commercially. 18 | 19 | The licensor cannot revoke these freedoms as long as you follow the 20 | license terms. 21 | 22 | **Under the following terms:** 23 | 24 | - **Attribution**---You must give appropriate credit, provide a link 25 | to the license, and indicate if changes were made. You may do so in 26 | any reasonable manner, but not in any way that suggests the licensor 27 | endorses you or your use. 28 | 29 | - **No additional restrictions**---You may not apply legal terms or 30 | technological measures that legally restrict others from doing 31 | anything the license permits. 32 | 33 | **Notices:** 34 | 35 | You do not have to comply with the license for elements of the 36 | material in the public domain or where your use is permitted by an 37 | applicable exception or limitation. 38 | 39 | No warranties are given. The license may not give you all of the 40 | permissions necessary for your intended use. For example, other rights 41 | such as publicity, privacy, or moral rights may limit how you use the 42 | material. 43 | -------------------------------------------------------------------------------- /CITATION.cff: -------------------------------------------------------------------------------- 1 | cff-version: 1.2.0 2 | message: "Please cite this paper as shown." 3 | authors: 4 | - family-names: "Sholler" 5 | given-names: "Dan" 6 | orcid: "https://orcid.org/0000-0003-2517-4317" 7 | - family-names: "Steinmacher" 8 | given-names: "Igor" 9 | orcid: "https://orcid.org/0000-0002-0612-5790" 10 | - family-names: "Ford" 11 | given-names: "Denae" 12 | orcid: "https://orcid.org/0000-0003-0654-4335" 13 | - family-names: "Averick" 14 | given-names: "Mara" 15 | orcid: "https://orcid.org/0000-0001-9659-6192" 16 | - family-names: "Hoye" 17 | given-names: "Mike" 18 | orcid: "https://orcid.org/0000-0001-9145-2595" 19 | - family-names: "Wilson" 20 | given-names: "Greg" 21 | orcid: "https://orcid.org/0000-0001-8659-8979" 22 | title: "Ten simple rules for helping newcomers become contributors to open projects" 23 | preferred-citation: 24 | type: article 25 | authors: 26 | - family-names: "Sholler" 27 | given-names: "Dan" 28 | orcid: "https://orcid.org/0000-0003-2517-4317" 29 | - family-names: "Steinmacher" 30 | given-names: "Igor" 31 | orcid: "https://orcid.org/0000-0002-0612-5790" 32 | - family-names: "Ford" 33 | given-names: "Denae" 34 | orcid: "https://orcid.org/0000-0003-0654-4335" 35 | - family-names: "Averick" 36 | given-names: "Mara" 37 | orcid: "https://orcid.org/0000-0001-9659-6192" 38 | - family-names: "Hoye" 39 | given-names: "Mike" 40 | orcid: "https://orcid.org/0000-0001-9145-2595" 41 | - family-names: "Wilson" 42 | given-names: "Greg" 43 | orcid: "https://orcid.org/0000-0001-8659-8979" 44 | title: "Ten simple rules for helping newcomers become contributors to open projects" 45 | doi: "10.1371/journal.pcbi.1007296" 46 | journal: "PLOS Computational Biology" 47 | volume: 15 48 | issue: 9 49 | year: 2019 50 | month: 9 51 | -------------------------------------------------------------------------------- /submission-2019-07-06.txt: -------------------------------------------------------------------------------- 1 | July 6, 2019 2 | 3 | To whom it may concern, 4 | 5 | Please find attached a revision to our paper "Ten Simple Rules for Helping Newcomers Become Contributors to Open Source Projects". We are very grateful for the comments made by Reviewer #1 (Erin Robinson), and have incorporated most of them in this revision (see below). 6 | 7 | Sincerely, 8 | 9 | Dan Sholler, Igor Steinmacher, Denae Ford, Mara Averick, Mike Hoye, and Greg Wilson 10 | 11 | gvwilson@third-bit.com 12 | 13 | - "Suggested reordering and combining of rules:" 14 | 15 | Agreed; rules have been reorganized largely as suggested. 16 | 17 | - "Rule 1: Code of conduct is important..." 18 | 19 | Reorganized as suggested. 20 | 21 | - "Rule 2 -- Make governance explicit is a good point, but muddied with citation and licensing." 22 | 23 | Agreed - separated. 24 | 25 | - "Would shy away from benevolent dictators as part of any governance" 26 | 27 | We have kept the description, since it is a common model, but have explained its weaknesses. 28 | 29 | - "Rule 3 -- Be welcoming -- suggest this is swapped with rule 1." 30 | 31 | Agreed. 32 | 33 | - "Rule 4 -- This rule should really emphasize, what's in it for the newcomer." 34 | 35 | Now incorporated in Rule 2 after reorganization suggested by reviewer. 36 | 37 | - "Rule 8 -- May consider meet-ups with collocated larger events as an option for projects." 38 | 39 | Good point :-) 40 | 41 | - "Rule 10 -- Most of what is included here is important as part of Rule 3." 42 | 43 | Agreed. 44 | 45 | - "I would broaden this last rule to acknowledge ALL contributors to your project." 46 | 47 | Good catch. 48 | 49 | - "I would recommend ending this paper on individual and collective acknowledgement." 50 | 51 | We have instead opted to end on "follow up", since that's the point at which being a newcomer ends and being a regular contributor begins. 52 | -------------------------------------------------------------------------------- /submission-2019-07-10.txt: -------------------------------------------------------------------------------- 1 | July 10, 2019 2 | 3 | To whom it may concern, 4 | 5 | Please find attached a revision to our paper "Ten Simple Rules for Helping Newcomers Become Contributors to Open Source Projects". We are very grateful for the comments made by Reviewer #1 (Erin Robinson), and have incorporated most of them in this revision (see below). We have also replaced the appendix with a figure as requested earlier today. 6 | 7 | Sincerely, 8 | 9 | Dan Sholler, Igor Steinmacher, Denae Ford, Mara Averick, Mike Hoye, and Greg Wilson 10 | 11 | gvwilson@third-bit.com 12 | 13 | - "Suggested reordering and combining of rules:" 14 | 15 | Agreed; rules have been reorganized largely as suggested. 16 | 17 | - "Rule 1: Code of conduct is important..." 18 | 19 | Reorganized as suggested. 20 | 21 | - "Rule 2 -- Make governance explicit is a good point, but muddied with citation and licensing." 22 | 23 | Agreed - separated. 24 | 25 | - "Would shy away from benevolent dictators as part of any governance" 26 | 27 | We have kept the description, since it is a common model, but have explained its weaknesses. 28 | 29 | - "Rule 3 -- Be welcoming -- suggest this is swapped with rule 1." 30 | 31 | Agreed. 32 | 33 | - "Rule 4 -- This rule should really emphasize, what's in it for the newcomer." 34 | 35 | Now incorporated in Rule 2 after reorganization suggested by reviewer. 36 | 37 | - "Rule 8 -- May consider meet-ups with collocated larger events as an option for projects." 38 | 39 | Good point :-) 40 | 41 | - "Rule 10 -- Most of what is included here is important as part of Rule 3." 42 | 43 | Agreed. 44 | 45 | - "I would broaden this last rule to acknowledge ALL contributors to your project." 46 | 47 | Good catch. 48 | 49 | - "I would recommend ending this paper on individual and collective acknowledgement." 50 | 51 | We have instead opted to end on "follow up", since that's the point at which being a newcomer ends and being a regular contributor begins. 52 | -------------------------------------------------------------------------------- /settings.tex: -------------------------------------------------------------------------------- 1 | \usepackage[top=0.85in,left=2.75in,footskip=0.75in]{geometry} 2 | 3 | % amsmath and amssymb packages, useful for mathematical formulas and symbols 4 | \usepackage{amsmath,amssymb} 5 | 6 | % Use adjustwidth environment to exceed column width (see example table in text) 7 | \usepackage{changepage} 8 | 9 | % Use Unicode characters when possible 10 | \usepackage[utf8x]{inputenc} 11 | 12 | % textcomp package and marvosym package for additional characters 13 | \usepackage{textcomp,marvosym} 14 | 15 | % cite package, to clean up citations in the main text. Do not remove. 16 | \usepackage{cite} 17 | 18 | % Use nameref to cite supporting information files (see Supporting Information section for more info) 19 | \usepackage{nameref,hyperref} 20 | 21 | % line numbers 22 | \usepackage[right]{lineno} 23 | 24 | % ligatures disabled 25 | \usepackage{microtype} 26 | \DisableLigatures[f]{encoding = *, family = * } 27 | 28 | % color can be used to apply background shading to table cells only 29 | \usepackage[table]{xcolor} 30 | 31 | % array package and thick rules for tables 32 | \usepackage{array} 33 | 34 | % enumerate package lets us use letters instead of numbers 35 | \usepackage{enumerate} 36 | 37 | % create "+" rule type for thick vertical lines 38 | \newcolumntype{+}{!{\vrule width 2pt}} 39 | 40 | % create \thickcline for thick horizontal lines of variable length 41 | \newlength\savedwidth 42 | \newcommand\thickcline[1]{% 43 | \noalign{\global\savedwidth\arrayrulewidth\global\arrayrulewidth 2pt}% 44 | \cline{#1}% 45 | \noalign{\vskip\arrayrulewidth}% 46 | \noalign{\global\arrayrulewidth\savedwidth}% 47 | } 48 | 49 | % \thickhline command for thick horizontal lines that span the table 50 | \newcommand\thickhline{\noalign{\global\savedwidth\arrayrulewidth\global\arrayrulewidth 2pt}% 51 | \hline 52 | \noalign{\global\arrayrulewidth\savedwidth}} 53 | 54 | \usepackage{color} 55 | 56 | % Remove comment for double spacing 57 | %\usepackage{setspace} 58 | %\doublespacing 59 | 60 | % Text layout 61 | \raggedright 62 | \setlength{\parindent}{0.5cm} 63 | \textwidth 5.25in 64 | \textheight 8.75in 65 | 66 | % Bold the 'Figure #' in the caption and separate it from the title/caption with a period 67 | % Captions will be left justified 68 | \usepackage[aboveskip=1pt,labelfont=bf,labelsep=period,justification=raggedright,singlelinecheck=off]{caption} 69 | \renewcommand{\figurename}{Fig} 70 | 71 | % Use the PLoS provided BiBTeX style 72 | \bibliographystyle{plos2015} 73 | 74 | % Remove brackets from numbering in List of References 75 | \makeatletter 76 | \renewcommand{\@biblabel}[1]{\quad#1.} 77 | \makeatother 78 | 79 | % Leave date blank 80 | \date{} 81 | 82 | % Header and Footer with logo 83 | \usepackage{lastpage,fancyhdr,graphicx} 84 | \usepackage{epstopdf} 85 | \pagestyle{myheadings} 86 | \pagestyle{fancy} 87 | \fancyhf{} 88 | \setlength{\headheight}{27.023pt} 89 | \lhead{\includegraphics[width=2.0in]{PLOS-submission.eps}} 90 | \rfoot{\thepage/\pageref{LastPage}} 91 | \renewcommand{\footrule}{\hrule height 2pt \vspace{2mm}} 92 | \fancyheadoffset[L]{2.25in} 93 | \fancyfootoffset[L]{2.25in} 94 | \lfoot{\sf PLOS} 95 | -------------------------------------------------------------------------------- /CODE_OF_CONDUCT.md: -------------------------------------------------------------------------------- 1 | # Code of Conduct 2 | 3 | In the interest of fostering an open and welcoming environment, we as 4 | contributors and maintainers pledge to making participation in our 5 | project and our community a harassment-free experience for everyone, 6 | regardless of age, body size, disability, ethnicity, gender identity 7 | and expression, level of experience, education, socio-economic status, 8 | nationality, personal appearance, race, religion, or sexual identity 9 | and orientation. 10 | 11 | ## Our Standards 12 | 13 | Examples of behavior that contributes to creating a positive 14 | environment include: 15 | 16 | * using welcoming and inclusive language, 17 | * being respectful of differing viewpoints and experiences, 18 | * gracefully accepting constructive criticism, 19 | * focusing on what is best for the community, and 20 | * showing empathy towards other community members. 21 | 22 | Examples of unacceptable behavior by participants include: 23 | 24 | * the use of sexualized language or imagery and unwelcome sexual 25 | attention or advances, 26 | * trolling, insulting/derogatory comments, and personal or political 27 | attacks, 28 | * public or private harassment, 29 | * publishing others' private information, such as a physical or 30 | electronic address, without explicit permission, and 31 | * other conduct which could reasonably be considered inappropriate in 32 | a professional setting 33 | 34 | ## Our Responsibilities 35 | 36 | Project maintainers are responsible for clarifying the standards of 37 | acceptable behavior and are expected to take appropriate and fair 38 | corrective action in response to any instances of unacceptable 39 | behavior. 40 | 41 | Project maintainers have the right and responsibility to remove, edit, 42 | or reject comments, commits, code, wiki edits, issues, and other 43 | contributions that are not aligned to this Code of Conduct, or to ban 44 | temporarily or permanently any contributor for other behaviors that 45 | they deem inappropriate, threatening, offensive, or harmful. 46 | 47 | ## Scope 48 | 49 | This Code of Conduct applies both within project spaces and in public 50 | spaces when an individual is representing the project or its 51 | community. Examples of representing a project or community include 52 | using an official project e-mail address, posting via an official 53 | social media account, or acting as an appointed representative at an 54 | online or offline event. Representation of a project may be further 55 | defined and clarified by project maintainers. 56 | 57 | ## Enforcement 58 | 59 | Instances of abusive, harassing, or otherwise unacceptable behavior 60 | may be reported by [emailing the project team](mailto:gvwilson@third-bit.com). 61 | All complaints will be reviewed and investigated and will result in a 62 | response that is deemed necessary and appropriate to the 63 | circumstances. The project team is obligated to maintain 64 | confidentiality with regard to the reporter of an incident. Further 65 | details of specific enforcement policies may be posted separately. 66 | 67 | Project maintainers who do not follow or enforce the Code of Conduct 68 | in good faith may face temporary or permanent repercussions as 69 | determined by other members of the project's leadership. 70 | 71 | ## Attribution 72 | 73 | This Code of Conduct is adapted from the [Contributor 74 | Covenant](https://www.contributor-covenant.org) version 1.4. 75 | -------------------------------------------------------------------------------- /feedback-2019-06-04.txt: -------------------------------------------------------------------------------- 1 | Overall, this is an interesting paper and provides useful guidance for 2 | open science, open source communities of effort. It is interesting that 3 | these rules are based on fairly young (few months - few years) and few 4 | dozen participants. Perhaps the focus on newcomers is because that is 5 | where the primary focus of these communities is right now. I would 6 | encourage authors to also consider what happens when these communities 7 | mature and what happens when they scale to 100 or 1000 participants? As 8 | a community manager it would be even more useful to me if there was a 9 | suggest 'best practice' for each rule or set of resources to explore to 10 | make these rules more immediately implementable. It would also be 11 | interesting if after this paper is published if communities that agree 12 | 'endorse' these rules and implement or share how they are fulfilling 13 | each rule -- a community seal of approval? 14 | 15 | Below are comments on each rule followed by suggestions for merging 16 | rules and reordering rules: 17 | 18 | Rule 1: Code of conduct is important, but the culture that it defines is 19 | critical. This is the current trendy item to mention, but a code of 20 | conduct is just one tool. Key questions here are: How do communities 21 | create a culture of collegial, open, sharing? It isn't with just a code 22 | of conduct at the start. It is also speaking up, if you see something 23 | say something. It is modeling appropriate behavior. People participate 24 | in open science or open source because there is something of personal or 25 | professional value or gain for them. Would also suggest tightening up 26 | the issues around reporting. Many communities do this badly and these 27 | points are good, but a little fragmented. May also suggest terming this 28 | community guidelines or rules of the road. 29 | 30 | Rule 2 -- Make governance explicit is a good point, but muddied with 31 | citation and licensing. This reviewer recommends a separate rule on 32 | community acknowledgement (see notes on rule 10). 33 | 34 | Would shy away from benevolent dictators as part of any governance 35 | because the risk is that project then lives and dies with one person. If 36 | this is steering communities towards best practices, identification of 37 | how someone becomes a member of the project to have a voice, what 38 | decisions are made collectively. Ideally, open source projects want the 39 | entire community to feel shared ownership. 40 | 41 | I might also suggest that simple and sloppy like the internet -- have 42 | governance that can evolve as the organization grows and matures and 43 | don't make it too complicated or heavy too soon. Borrow what you like 44 | from other organizations and be transparent as your org evolves. It is 45 | easy to let this be a critical stumbling block of not moving forward. 46 | 47 | Rule 3 -- Be welcoming -- suggest this is swapped with rule 1. Be 48 | welcoming should be first rule because that is critical to growth, Rule 49 | 2 -- have explicit governance and Rule 3 -- part of the governance is a 50 | code of conduct. Onboarding guidance and role of veteran members is 51 | great idea. 52 | 53 | Rule 4 -- This rule should really emphasize, what's in it for the 54 | newcomer. Newcomers must have a compelling reason to participate and 55 | there must be more value in doing this collaboratively than alone. 56 | 57 | Rule 5 -- See Rule 9. 58 | 59 | Rules 6 & 7 potentially combine 6&7 shortening 6 with just paragraph of 60 | making it easy to find. 61 | 62 | Rule 8 -- May consider meet-ups with collocated larger events as an 63 | option for projects. Many projects hold workshops/training/demos with 64 | larger conferences where their attendees may be. This rule confuses 65 | gaining new members as purpose with meeting face to face for governance 66 | or strategic direction decisions. 67 | 68 | There may be an element of marketing your project here -- are there 69 | slide decks, stickers, postcards etc that explain simply what your 70 | project does. What have successful communities done that help growth? I 71 | think members are empowered to champion the community and the best way 72 | to gain relevant newcomers is when their peers bring them in. What else 73 | do you do to market and grow your community? Are there virtual ways to 74 | do this? 75 | 76 | Rule 9 -- Suggest combining rules 5 & 9. With Rule 5 taking the lead and 77 | this being a subpart, installing could be an LPP. 78 | 79 | Open source projects developing code to support open science are a 80 | further niche to just open science projects that are not building 81 | infrastructure or maintaining code. The former seems to be what this 82 | paper is geared toward and this rule is emphasizing that. The former 83 | also has a 'product', the later may not have a product and with no 84 | product it is much harder for newcomers to find value or reasons to 85 | contribute. May consider clarifying the scope of these rules to open 86 | source, open science communities developing code or think of way to 87 | broaden this rule. 88 | 89 | Rule 10 -- Most of what is included here is important as part of Rule 3 90 | -- be welcoming. 91 | 92 | I would broaden this last rule to acknowledge ALL contributors to your 93 | project. 94 | 95 | Points about celebrating first contributions may fit in Rule 4 and 96 | points about mentoring may fit in the welcome rule or rule 6 about 97 | navigating the community documentation. 98 | 99 | I would recommend ending this paper on individual and collective 100 | acknowledgement. Citation of research objects is a new area where 101 | software is leading with software citation, but open science communities 102 | are generally not cited. Without a foundational community paper, the 103 | community is not getting credit. 104 | 105 | Further things to consider: How do you create a culture where peers 106 | acknowledge each other, that individuals contributing get credit to 107 | further their careers and that the project as a whole also increases its 108 | value and the positive reinforcement draws in new members who want to be 109 | associated with this work, want to use the tool, etc. 110 | 111 | **Suggested reordering and combining of rules:** 112 | 113 | Rule 3: Be welcoming. 114 | 115 | Rule 4: Help potential contributors evaluate if the project is a good 116 | fit. (Why contribute in the first place) 117 | 118 | Rule 2: Make governance and licensing explicit. -- Remove citation and 119 | include with Rule 10. 120 | 121 | Rule 6: Make knowledge findable and keep it up to date. 122 | 123 | Rule 7: Provide an easy, complete, and up-to-date guide to contributing. 124 | 125 | Rule 1: Have and enforce a code of conduct. (once you have explicit 126 | governance and easy to find guidance then make sure your code of conduct 127 | is visible). This sets the stage for contributions and participation. 128 | 129 | Rule 5: Develop forms of legitimate peripheral participation 130 | 131 | Rule 9: Make it easy for newcomers to set up. 132 | 133 | Rule 8: Use opportunities for in-person interaction, but with care. (Let 134 | everyone feel like a project ambassador/owner); 135 | 136 | Rule 10: Follow up on success. (Broaden to acknowledge ALL 137 | contributions) 138 | 139 | With this combination of rules, it leaves space for potentially a few 140 | additions. I would suggest considering rules on failures in the 141 | community or newcomer failures. The authors may also think about a rule 142 | on evaluation of community? How do you know if you are successful? Is it 143 | just \# of newcomers or sustaining membership beyond the newcomer phase 144 | or sustaining the project. This is an evolving area of research, but 145 | would be good to flag that more is not always better. 146 | -------------------------------------------------------------------------------- /10-newcomers.bib: -------------------------------------------------------------------------------- 1 | @misc{apache-governance, 2 | author = {{Apache Software Foundation}}, 3 | title = {The Apache Software Foundation: How It Works}, 4 | howpublished = {https://www-us.apache.org/foundation/how-it-works.html}, 5 | year = {Accessed March 27, 2019} 6 | } 7 | 8 | @misc{apache-guidelines, 9 | author = {{Apache Software Foundation}}, 10 | title = {Introduction to Contributing to Apache OpenOffice}, 11 | howpublished = {https://openoffice.apache.org/orientation/intro-contributing.html}, 12 | year = {Accessed February 16, 2019} 13 | } 14 | 15 | @book{aurora2019, 16 | author = {Valerie Aurora and Mary Gardiner}, 17 | title = {How to Respond to Code of Conduct Reports}, 18 | publisher = {Frame Shift Consulting LLC}, 19 | edition = {Version 1.1}, 20 | year = {2019}, 21 | isbn = {978-1386922575}, 22 | link = {https://files.frameshiftconsulting.com/books/cocguide.pdf} 23 | } 24 | 25 | @article{baltes2018, 26 | author = {Sebastian Baltes and Lorik Dumani and Christoph Treude and Stephan Diehl}, 27 | title = {The Evolution of Stack Overflow Posts: Reconstruction and Analysis}, 28 | journal = {CoRR}, 29 | volume = {abs/1811.00804}, 30 | year = {2018}, 31 | archivePrefix = {arXiv}, 32 | eprint = {1811.00804}, 33 | biburl = {https://dblp.org/rec/bib/journals/corr/abs-1811-00804} 34 | } 35 | 36 | @inproceedings{barcomb2019, 37 | author = {Ann Barcomb and Klaas-Jan Stol and Dirk Riehle and Brian Fitzgerald}, 38 | title = {Why Do Episodic Volunteers Stay in FLOSS Communities?}, 39 | booktitle = {Proc.\ 2019 International Conference on Software Engineering ({ICSE'19})}, 40 | year = {2019}, 41 | publisher = {{ACM} Press} 42 | } 43 | 44 | @misc{bezroukov1999, 45 | author = {Nikolai Bezroukov}, 46 | title = {A Second Look at the Cathedral and the Bazaar}, 47 | howpublished = {https://firstmonday.org/article/view/708/618}, 48 | year = {1999} 49 | } 50 | 51 | @misc{brown2019, 52 | author = {C.\ Titus Brown}, 53 | title = {Sustaining open source: thinking about communities of effort}, 54 | howpublished = {http://ivory.idyll.org/blog/author/c-titus-brown.html}, 55 | year = {Accessed March 21, 2019} 56 | } 57 | 58 | @misc{carpentries-bylaws, 59 | title = {The Carpentries Bylaws}, 60 | howpublished = {https://docs.carpentries.org/topic\_folders/governance/index.html}, 61 | year = {Accessed February 16, 2019} 62 | } 63 | 64 | @article{qureshi2011, 65 | title = {Socialization in open source software projects: A growth mixture modeling approach}, 66 | author = {Israr Qureshi and Yulin Fang}, 67 | journal = {Organizational Research Methods}, 68 | volume = {14}, 69 | number = {1}, 70 | pages = {208--238}, 71 | year = {2011}, 72 | publisher = {SAGE Publications Sage CA: Los Angeles, CA} 73 | } 74 | 75 | 76 | @inproceedings{cherubini2007, 77 | author = {Mauro Cherubini and Gina Venolia and Rob DeLine and Andrew J. Ko}, 78 | title = {Let's Go to the Whiteboard: How and Why Software Developers Use Drawings}, 79 | booktitle = {Proc.\ 2007 Conference on Human Factors in Computing Systems ({CHI'07})}, 80 | year = {2007}, 81 | publisher = {Association for Computing Machinery ({ACM})}, 82 | doi = {10.1145/1240624.1240714} 83 | } 84 | 85 | @misc{covenant, 86 | title = {Contributor Covenant}, 87 | edition = {Version 1.4.1}, 88 | howpublished = {https://www.contributor-covenant.org/}, 89 | year = {Accessed February 14, 2019} 90 | } 91 | 92 | @inproceedings{dagenais2010, 93 | author = {Barth{\'{e}}l{\'{e}}my Dagenais and Harold Ossher and Rachel K. E. Bellamy and Martin P. Robillard and Jacqueline P. de Vries}, 94 | title = {Moving Into a New Software Project Landscape}, 95 | booktitle = {Proc.\ 2010 International Conference on Software Engineering ({ICSE'10})}, 96 | year = {2010}, 97 | publisher = {{ACM} Press}, 98 | doi = {10.1145/1806799.1806842} 99 | } 100 | 101 | @article{doherty1997, 102 | author = {Gwyenth Doherty-Sneddon and Claire O{\textquotesingle}Malley and Simon Garrod and Anne Anderson and et al}, 103 | title = {Face-to-face and video-mediated communication: A comparison of dialogue structure and task performance.}, 104 | journal = {Journal of Experimental Psychology: Applied}, 105 | volume = {3}, 106 | number = {2}, 107 | pages = {105--125}, 108 | year = {1997}, 109 | doi = {10.1037/1076-898x.3.2.105}, 110 | publisher = {American Psychological Association ({APA})} 111 | } 112 | 113 | @inproceedings{ford2016, 114 | author = {Denae Ford and Justin Smith and Philip J. Guo and Chris Parnin}, 115 | title = {Paradise Unplugged: Identifying Barriers for Female Participation on Stack Overflow}, 116 | booktitle = {Proc.\ 2016 ACM SIGSOFT International Symposium on Foundations of Software Engineering ({FSE'16})}, 117 | series = {FSE 2016}, 118 | year = {2016}, 119 | isbn = {978-1-4503-4218-6}, 120 | pages = {846--857}, 121 | doi = {10.1145/2950290.2950331}, 122 | publisher = {{ACM} Press} 123 | } 124 | 125 | @inproceedings{fagerholm2014, 126 | author = {Fabian Fagerholm and Alejandro S. Guinea and J\"{u}rgen M\"{u}nch and Jay Borenstein}, 127 | title = {The role of mentoring and project characteristics for onboarding in open source software projects}, 128 | booktitle = {Proc.\ 2014 International Symposium on Empirical Software Engineering and Measurement ({ESEM'14})}, 129 | publisher = {{ACM} Press}, 130 | year = {2014}, 131 | doi = {10.1145/2652524.2652540} 132 | } 133 | 134 | @inproceedings{ford2018, 135 | author = {Denae Ford and Kristina Lustig and Jeremy Banks and Chris Parnin}, 136 | title = {"We Don't Do That Here": How Collaborative Editing with Mentors Improves Engagement in Social {Q\&A} Communities}, 137 | booktitle = {Proc.\ 2018 CHI Conference on Human Factors in Computing Systems}, 138 | series = {CHI 2018}, 139 | year = {2018}, 140 | isbn = {978-1-4503-5620-6}, 141 | pages = {608:1--608:12}, 142 | articleno = {608}, 143 | doi = {10.1145/3173574.3174182} 144 | } 145 | 146 | @book{fogel2005, 147 | author = {Karl Fogel}, 148 | title = {Producing Open Source Software: How to Run a Successful Free Software Project}, 149 | publisher = {O'Reilly Media}, 150 | year = {2005}, 151 | isbn = {978-0596007591}, 152 | link = {https://producingoss.com/} 153 | } 154 | 155 | @article{freeman1972, 156 | author = {Jo Freeman}, 157 | title = {The Tyranny of Structurelessness}, 158 | journal = {The Second Wave}, 159 | volume = {2}, 160 | number = {1}, 161 | year = {1972} 162 | } 163 | 164 | @article{gallupe1990, 165 | author = {R. Brent Gallupe and James D. McKeen}, 166 | title = {Enhancing Computer-Mediated Communication: An experimental investigation into the use of a Group Decision Support System for face-to-face versus remote meetings}, 167 | journal = {Information {\&} Management}, 168 | volume = {18}, 169 | number = {1}, 170 | pages = {1--13}, 171 | month = {jan}, 172 | year = {1990}, 173 | publisher = {Elsevier {BV}}, 174 | doi = {10.1016/0378-7206(90)90059-q} 175 | } 176 | 177 | @misc{github-rec, 178 | author = {GitHub}, 179 | title = {Setting Guidelines for Repository Contributors}, 180 | howpublished = {https://help.github.com/articles/setting-guidelines-for-repository- contributors/}, 181 | year = {Accessed February 16, 2019} 182 | } 183 | 184 | @misc{gnome-newcomers, 185 | title = {GNOME Newcomers' Guide}, 186 | howpublished = {https://wiki.gnome.org/Newcomers/SubmitContribution}, 187 | year = {Accessed February 16, 2019}, 188 | } 189 | 190 | @article{huppenkothen2018, 191 | author = {Daniela Huppenkothen and Anthony Arendt and David W. Hogg and Karthik Ram and Jacob T. VanderPlas and Ariel Rokem}, 192 | title = {Hack weeks as a model for data science education and collaboration}, 193 | journal = {Proc.\ National Academy of Sciences}, 194 | volume = {115}, 195 | number = {36}, 196 | pages = {8872--8877}, 197 | month = {aug}, 198 | year = {2018}, 199 | publisher = {Proc.\ National Academy of Sciences}, 200 | doi = {10.1073/pnas.1717196115} 201 | } 202 | 203 | @misc{jupyter-coc, 204 | author = {{Project Jupyter}}, 205 | title = {Code of Conduct}, 206 | howpublished = {https://github.com/jupyter/governance/blob/master/conduct/code\_of\_conduct.md}, 207 | year = {Accessed February 14, 2019} 208 | } 209 | 210 | @book{kraut2012, 211 | editor = {Robert E. Kraut and Paul Resnick}, 212 | title = {Building Successful Online Communities: Evidence-Based Social Design}, 213 | publisher = {MIT Press}, 214 | isbn = {978-0262016575} 215 | } 216 | 217 | @inproceedings{labuschagne2015, 218 | author = {Adriaan Labuschagne and Reid Holmes}, 219 | title = {Do Onboarding Programs Work?}, 220 | booktitle = {Proc.\ 2015 Working Conference on Mining Software Repositories ({MSR'15})}, 221 | publisher = {{IEEE}}, 222 | year = {2015}, 223 | doi = {10.1109/msr.2015.45} 224 | } 225 | 226 | @book{lave1991, 227 | author = {Jean Lave and Etienne Wenger}, 228 | title = {Situated Learning: Legitimate Peripheral Participation}, 229 | publisher = {Cambridge University Press}, 230 | year = {1991}, 231 | isbn = {978-0521423748} 232 | } 233 | 234 | @misc{libreoffice-filtered, 235 | author = {{The Document Foundation}}, 236 | title = {LibreOffice Easy Hacks by Required Skill}, 237 | howpublished = {https://wiki.documentfoundation.org/Development/EasyHacks/by\_Required\_Skill}, 238 | year = {Accessed March 21, 2019} 239 | } 240 | 241 | @article{maenpaa2018, 242 | author = {Hanna M\"{a}enp\"{a}\"{a} and Simo M\"{a}kinen and Terhi Kilamo and Tommi Mikkonen and Tomi M\"{a}nnist\"{o} and Paavo Ritala}, 243 | title = {Organizing for openness: six models for developer involvement in hybrid {OSS} projects}, 244 | journal = {Journal of Internet Services and Applications}, 245 | volume = {9}, 246 | number = {1}, 247 | month = {aug}, 248 | year = {2018}, 249 | publisher = {Springer Nature}, 250 | doi = {10.1186/s13174-018-0088-1} 251 | } 252 | 253 | @article{minahan1986, 254 | author = {Anne Minahan}, 255 | title = {Martha's Rules}, 256 | journal = {Affilia}, 257 | volume = {1}, 258 | number = {2}, 259 | pages = {53--56}, 260 | month = {6}, 261 | year = {1986}, 262 | publisher = {{SAGE} Publications}, 263 | doi = {10.1177/088610998600100206} 264 | } 265 | 266 | @misc{mozilla, 267 | author = {{Mozilla Foundation}}, 268 | title = {Mozilla Firefox}, 269 | howpublished = {https://www.mozilla.org/en-US/}, 270 | year = {Accessed March 21, 2019} 271 | } 272 | 273 | @misc{my-github-resume, 274 | author = {David Coallier}, 275 | title = {My GitHub Resume}, 276 | howpublished = {https://resume.github.io/}, 277 | year = {Accessed March 21, 2019} 278 | } 279 | 280 | @incollection{nardi2002, 281 | author = {Bonnie A. Nardi and Steve Whittaker}, 282 | title = {The place of face-to-face communication in distributed work}, 283 | booktitle = {Distributed Work}, 284 | editor = {P. Hinds and S. Kiesler}, 285 | pages = {83--110}, 286 | publisher = {{MIT} Press}, 287 | year = {2002} 288 | } 289 | 290 | @article{omalley1996, 291 | author = {Claire O'Malley and Steve Langton and Anne Anderson and Gwyneth Doherty-Sneddon and Vicki Bruce}, 292 | title = {Comparison of face-to-face and video-mediated interaction}, 293 | journal = {Interacting with Computers}, 294 | volume = {8}, 295 | number = {2}, 296 | pages = {177--192}, 297 | month = {jun}, 298 | year = {1996}, 299 | doi = {10.1016/0953-5438(96)01027-2}, 300 | publisher = {Oxford University Press ({OUP})} 301 | } 302 | 303 | @misc{openhatch, 304 | title = {OpenHatch}, 305 | howpublished = {http://openhatch.org/}, 306 | year = {Accessed March 27 2019} 307 | } 308 | 309 | @misc{psf-bylaws, 310 | title = {Python Software Foundation Bylaws}, 311 | howpublished = {https://www.python.org/psf/bylaws/}, 312 | year = {Accessed February 16, 2019} 313 | } 314 | 315 | @misc{raymond2001, 316 | author = {Eric S. Raymond}, 317 | title = {The Cathedral and the Bazaar}, 318 | publisher = {O'Reilly Media}, 319 | year = {2001}, 320 | isbn = {978-0596001087} 321 | } 322 | 323 | @misc{ropensci-coc, 324 | title = {rOpenSci Code of Conduct}, 325 | edition = {Version 2.0}, 326 | howpublished = {https://ropensci.org/code-of-conduct/}, 327 | year = {Accessed February 14, 2019} 328 | } 329 | 330 | @misc{ropensci-guidelines, 331 | title = {rOpenSci Packages: Develpoment, Maintenance, and Peer Review}, 332 | chapter = {14: Contributing Guide}, 333 | howpublished = {https://ropensci.github.io/dev\_guide/}, 334 | year = {Accessed February 16, 2019} 335 | } 336 | 337 | @misc{numpy-coc, 338 | author = {{SciPy Community}}, 339 | title = {NumPy Code of Conduct}, 340 | howpublished = {https://www.numpy.org/devdocs/dev/conduct/code\_of\_conduct.html}, 341 | year = {Accessed February 14, 2019} 342 | } 343 | 344 | @inproceedings{sarma2016, 345 | author = {Anita Sarma and Xiaofan Chen and Sandeep Kuttal and Laura Dabbish and Zhendong Wang}, 346 | title = {Hiring in the Global Stage: Profiles of Online Contributions}, 347 | booktitle = {Proc.\ 2016 {IEEE} International Conference on Global Software Engineering}, 348 | series = {ICGSE 2016}, 349 | year = {2016}, 350 | publisher = {Institute of Electrical and Electronics Engineers ({IEEE})}, 351 | doi = {10.1109/icgse.2016.35} 352 | } 353 | 354 | @misc{scipy-coc, 355 | title = {SciPy Code of Conduct}, 356 | edition = {Version 1.2.0}, 357 | howpublished = {https://docs.scipy.org/doc/scipy/reference/dev/conduct/code\_of\_conduct.html}, 358 | year = {Accessed February 14, 2019} 359 | } 360 | 361 | @inproceedings{singh2012, 362 | author = {Vandana Singh}, 363 | title = {Newcomer integration and learning in technical support communities for open source software}, 364 | booktitle = {Proc.\ 2012 {ACM} International Conference on Supporting Group Work - {GROUP'12}}, 365 | year = {2012}, 366 | publisher = {{ACM} Press}, 367 | doi = {10.1145/2389176.2389186} 368 | } 369 | 370 | @inproceedings{steinmacher2013, 371 | author = {Igor Steinmacher and Igor Wiese and Ana Paula Chaves and Marco Aurelio Gerosa}, 372 | title = {Why do newcomers abandon open source software projects?}, 373 | booktitle = {Proc.\ 2013 International Workshop on Cooperative and Human Aspects of Software Engineering ({CHASE'13})}, 374 | month = {may}, 375 | year = {2013}, 376 | publisher = {Institute of Electrical and Electronics Engineers ({IEEE})}, 377 | doi = {10.1109/chase.2013.6614728} 378 | } 379 | 380 | @inproceedings{steinmacher2014, 381 | author = {Igor Steinmacher and {Igor Scaliante} Wiese and Tayana Conte and {Marco Aurelio} Gerosa and David Redmiles}, 382 | title = {The Hard Life of Open Source Software Project Newcomers}, 383 | booktitle = {Proc.\ 2014 International Workshop on Cooperative and Human Aspects of Software Engineering ({CHASE'14})}, 384 | publisher = {{ACM} Press}, 385 | year = {2014}, 386 | doi = {10.1145/2593702.2593704}, 387 | } 388 | 389 | @inproceedings{steinmacher2015, 390 | author = {Igor Steinmacher and Tayana Conte and Marco Aur{\'{e}}lio Gerosa and David Redmiles}, 391 | title = {Social Barriers Faced by Newcomers Placing Their First Contribution in Open Source Software Projects}, 392 | booktitle = {Proc.\ 2015 {ACM} Conference on Computer Supported Cooperative Work {\&} Social Computing}, 393 | series = {CSCW 2015}, 394 | year = {2015}, 395 | publisher = {{ACM} Press}, 396 | doi = {10.1145/2675133.2675215} 397 | } 398 | 399 | @inproceedings{steinmacher2016, 400 | author = {Igor Steinmacher and Tayana Uchoa Conte and Christoph Treude and Marco Aur{\'{e}}lio Gerosa}, 401 | title = {Overcoming open source project entry barriers with a portal for newcomers}, 402 | booktitle = {Proc.\ 2016 International Conference on Software Engineering ({ICSE'16})}, 403 | year = {2016}, 404 | publisher = {{ACM} Press}, 405 | doi = {10.1145/2884781.2884806} 406 | } 407 | 408 | @inproceedings{steinmacher2018a, 409 | author = {Igor Steinmacher and Gustavo Pinto and Igor Scaliante Wiese and Marco A. Gerosa}, 410 | title = {Almost There: A Study on Quasi-Contributors in Open-Source Software Projects}, 411 | booktitle = {Proc.\ 2018 International Conference on Software Engineering ({ICSE'18})}, 412 | publisher = {{ACM} Press}, 413 | year = {2018}, 414 | doi = {10.1145/3180155.3180208} 415 | } 416 | 417 | @Article{steinmacher2018b, 418 | author = {Igor Steinmacher and Christoph Treude and Marco A. Gerosa}, 419 | journal = {{IEEE} Software}, 420 | title = {Let Me In: Guidelines for the Successful Onboarding of Newcomers to Open Source Projects}, 421 | year = {2018}, 422 | doi = {10.1109/MS.2018.110162131} 423 | } 424 | 425 | @inproceedings{tourani2017, 426 | author = {Parastou Tourani and Bram Adams and Alexander Serebrenik}, 427 | title = {Code of Conduct in Open Source Projects}, 428 | booktitle = {Proc.\ 2017 International Conference on Software Analysis, Evolution and Reengineering ({SANER'17})}, 429 | publisher = {{IEEE}}, 430 | year = {2017}, 431 | doi = {10.1109/saner.2017.7884606} 432 | } 433 | 434 | @book{wenger1999, 435 | author = {Etienne Wenger}, 436 | title = {Communities of Practice: Learning, Meaning, and Identity}, 437 | publisher = {Cambridge University Press}, 438 | year = {1999}, 439 | isbn = {978-0521663632} 440 | } 441 | 442 | @article{zanatta2017, 443 | author = {Alexandre Lazaretti Zanatta and Igor Steinmacher and Leticia Santos Machado and Cleidson R.B. de Souza and Rafael Prikladnicki}, 444 | title = {Barriers Faced by Newcomers to Software-Crowdsourcing Projects}, 445 | journal = {{IEEE} Software}, 446 | volume = {34}, 447 | number = {2}, 448 | month = {mar}, 449 | year = {2017}, 450 | pages = {37--43}, 451 | doi = {10.1109/ms.2017.32}, 452 | publisher = {Institute of Electrical and Electronics Engineers ({IEEE})} 453 | } 454 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Ten Simple Rules for Helping Newcomers Become Contributors to Open Projects 2 | 3 | Dan Sholler, Igor Steinmacher, Denae Ford, Mara Averick, Mike Hoye, and Greg Wilson 4 | 5 | These authors contributed equally to this work. 6 | 7 | ## Abstract 8 | 9 | To survive and thrive, a community must attract and retain new members 10 | and help them be productive. The 10 simple rules in this paper describe 11 | ways to do this that are suitable for projects in open source, open 12 | science, and open education, and are based on both current research and 13 | direct experience. 14 | 15 | ## Introduction 16 | 17 | To survive and thrive, a community must attract new members, retain 18 | them, and help them be productive [@qureshi2011]. As openness becomes 19 | the norm in research, software development, and education, knowing how 20 | to do this has become a essential skill for principal investigators and 21 | community managers alike. A growing body of knowledge in sociology, 22 | anthropology, education, and software engineering can guide decisions 23 | about how to facilitate this. 24 | 25 | What exactly do we mean by "community"? In the case of open source and 26 | open science, the most usual meaning is a "community of practice". As 27 | defined by Lave and Wenger [@lave1991; @wenger1999], groups as diverse 28 | as knitting circles, oncology researchers, and web designers share three 29 | key characteristics: 30 | 31 | 1. Participants have a common product or purpose that they work on or 32 | toward. 33 | 34 | 2. They are mutually engaged, *i.e.*, they assist and mentor each 35 | another. 36 | 37 | 3. They develop shared resources and domain knowledge. 38 | 39 | Brown [@brown2019] specializes this to define a "community of effort" 40 | as, "*...a community formed in pursuit of a common goal. The goal can be 41 | definite or indefinite in time, and may not be clearly defined, but it 42 | is something that (generally speaking) the community is aligned on.*" 43 | People working to preserve coral reefs in the face of global climate 44 | change are an example of such a community. No central organization 45 | coordinates their work, but the scientists who study coral reefs, the 46 | environmentalists who work to protect them, and the citizens who support 47 | them financially and politically are aware of each other's efforts, 48 | collaborate in ad hoc ways, and are conscious of contributing toward a 49 | shared purpose. 50 | 51 | Open source software projects are also communities of effort. For 52 | example, the Mozilla Firefox [@mozilla] community includes a mix of paid 53 | professionals, highly-involved volunteers, and occasional contributors 54 | who not only create software, documentation, and tutorials, but also 55 | organize events, answer questions in online forums, mentor newcomers, 56 | and advocate for open standards. 57 | 58 | Every community of effort has unique features, but they have enough in 59 | common to profit from one another's experience. The 10 rules laid out 60 | below are based on studies of such communities and on the authors' 61 | experience as members, leaders, and observers. Our focus is on small and 62 | medium-sized projects, i.e., ones that have a handful to a few hundreds 63 | participants and are a few months to a few years old, but may not (yet) 64 | have any formal legal standing such as incorporation as a non-profit. 65 | 66 | ### Acknowledgments 67 | 68 | The authors are grateful to everyone who gave feedback on early versions 69 | of this paper, and particularly to Erin Robinson for her detailed, 70 | knowledgeable, and helpful critique. 71 | 72 | ## Rule 1: Be welcoming. 73 | 74 | Karl Fogel wrote [@fogel2005], "If a project doesn't make a good first 75 | impression, newcomers may wait a long time before giving it a second 76 | chance." Other authors have empirically confirmed the importance of kind 77 | and polite social environments in open source projects 78 | [@singh2012; @steinmacher2013; @steinmacher2018a]. Therefore, projects 79 | should not just say that they welcome new members: they should make a 80 | proactive effort to foster positive feelings in them. 81 | 82 | - Post a welcome message on the project's social media pages, Slack 83 | channels, forums, or email lists. Projects might consider 84 | maintaining a dedicated "Welcome" channel or list, where a project 85 | lead or community manager writes a short post asking newcomers to 86 | introduce themselves. 87 | 88 | - Offer assistance in finding ways to make an initial contribution. 89 | 90 | - Direct the newcomer to project members who have a similar background 91 | or skill set so as to demonstrate fit to the newcomer. 92 | 93 | - Point the newcomer to essential project resources (e.g., the 94 | contribution guidelines). 95 | 96 | - Clearly identify work items they can start with. A growing number of 97 | projects explicitly tag bugs or issues as "suitable for newcomers", 98 | and ask established members not to fix them in order to ensure there 99 | are suitable places for new arrivals to start work. 100 | 101 | Projects can further designate one or two members to serve as a 102 | point-of-contact for each newcomer. Doing this may reduce the newcomer's 103 | hesitancy to ask questions, particularly when they are told from the 104 | outset that there are no dumb questions in the community. 105 | 106 | ## Rule 2: Help potential contributors evaluate if the project is a good fit. 107 | 108 | People could contribute to many different projects; the first and most 109 | important step in being welcoming is to help them determine whether your 110 | project is a good fit for their interests and abilities. Their decision 111 | to contribute can be related to reputation or external needs, but also 112 | to a desire to learn or give back to the community. In all of these 113 | cases, the more you help newcomers understand if this is the right 114 | project for them, the more quickly they will either start contributing 115 | or look elsewhere. 116 | 117 | To do this, the project should explicitly state what the different types 118 | of skills required are. This information should be easily accessible and 119 | guide new members to the tasks they may handle. LibreOffice, for 120 | example, provides a way for developers to filter available tasks by 121 | required skills and difficulty [@libreoffice-filtered]. 122 | 123 | The project should also help developers evaluate their skills, since 124 | "basic Python skills" means very different things to different people. 125 | Tools like My GitHub Resume [@my-github-resume] and Visual 126 | Resume [@sarma2016] that aggregate information from previous 127 | contributions can help with this assessment, while the now-defunct 128 | OpenHatch project [@openhatch] aggregated entry-level issues from a 129 | variety of open source projects and classified them according to 130 | language and other required skills to provide a one-stop portal for 131 | finding appropriate projects. 132 | 133 | ## Rule 3: Make governance explicit. 134 | 135 | Raymond's "The Cathedral and the Bazaar" [@raymond2001] described an 136 | egalitarian world in which everyone could contribute equally to open 137 | projects. Two decades later, we can see how unequal and unwelcoming the 138 | supposedly egalitarian "bazaar" of open source can be if authority lies 139 | with those willing to shout loudest and longest. As Bezroukov pointed 140 | out [@bezroukov1999], Raymond ignored the realities of how power arises, 141 | becomes concentrated in a few hands, and is then used to perpetuate 142 | itself. 143 | 144 | Bezroukov's criticism drew on Freeman's influential essay "The Tyranny 145 | of Structurelessness" [@freeman1972], which explained how an apparent 146 | lack of structure in organizations "...too often disguised an informal, 147 | unacknowledged and unaccountable leadership that was all the more 148 | pernicious because its very existence was denied." The solution is to 149 | make a project's governance explicit so that people know who makes which 150 | decisions. 151 | 152 | Large, well-established projects that incorporate as non-profits are 153 | required to promulgate bylaws, such as those for the Python Software 154 | Foundation [@psf-bylaws]. What smaller projects should do is less 155 | well-documented, but generally falls under one of three 156 | headings [@fogel2005]. The first is a "benevolent dictator" (often the 157 | project founder), who the community agrees has final say on important 158 | issues. This model is common in young or small projects, but is brittle, 159 | and inevitably fosters the emergence of unofficial (and hence 160 | unaccountable) de facto leaders in specific areas. 161 | 162 | The second model formalizes a consensus-building process in which the 163 | whole community can take part. One example is Martha's 164 | Rules [@minahan1986] (summarized in the appendix), under which anyone 165 | can put forward proposals, but those proposals are only adopted once it 166 | is clear that most people are not strongly opposed. The third model is 167 | based on elected representation. In the 168 | Carpentries [@carpentries-bylaws], for example, the electorate includes 169 | anyone who has: 170 | 171 | - completed instructor certification in the preceding year; 172 | 173 | - completed certification in the last two years and taught at least 174 | one workshop; 175 | 176 | - been certified for more than two years and has taught at least twice 177 | in that time; or 178 | 179 | - made a significant contribution to lesson development, 180 | infrastructure, or other activities as determined by the Executive 181 | Council. 182 | 183 | Decisions are then made by those elected, though they may decide or be 184 | required to take some matters to a referendum vote. 185 | 186 | More complex models are possible [@apache-governance], but the most 187 | important thing is to decide on the rules well in advance of contentious 188 | issues emerging, since tempers may already be running hot by the time 189 | this point is reached. 190 | 191 | ## Rule 4: Keep knowledge up to date and findable. 192 | 193 | When starting to contribute to a project, newcomers must orient 194 | themselves in an unfamiliar landscape [@dagenais2010]. It is therefore 195 | important to make sure that all necessary information is both accessible 196 | and findable. A single project may use wikis, files in GitHub, shared 197 | Google Docs, old tweets or Slack messages, and email archives; keeping 198 | information about a specific topic in a single place and clearly 199 | defining the purpose of each communication medium saves newcomers from 200 | having to navigate multiple unfamiliar data sources to find what they 201 | need. Doing this makes newcomers more confident and 202 | oriented [@steinmacher2016]. 203 | 204 | At the same time, outdated documentation may lead newcomers to a wrong 205 | understanding of the project, which is also demotivating. While it may 206 | be hard to keep material up to date, community members should at least 207 | remove or clearly mark outdated information. Signalling the absence or 208 | staleness of material can save newcomers time and also suggest 209 | opportunities for them to make contributions that they themselves would 210 | find useful. 211 | 212 | One special case of this rule is to provide "how to contribute" 213 | guidelines in easy-to-find, readily-available places. Many projects 214 | follow GitHub's recommendation for placing such information in a 215 | `CONTRIBUTING.md` file [@github-rec]. Other projects, such as the Apache 216 | Open Office Suite and rOpenSci, provide newcomer manuals and learning 217 | modules accessed through a web 218 | interface [@apache-guidelines; @ropensci-guidelines]. Still others take 219 | a more interactive approach; for example, the GNOME project's Newcomers 220 | Guide [@gnome-newcomers], walks potential contributors through the 221 | contribution pipeline: choosing a project, acquiring and installing the 222 | necessary computing tools, finding problems or choosing issues to work 223 | on, submitting changes, and following up on feedback. 224 | 225 | Such guidelines do more than just describe how to contribute. First, 226 | their mere existence can ease newcomers' hesitation about whether or not 227 | their work is sufficient and suitable for the project. Second, they 228 | provide a centralized, well-organized description of resources that a 229 | newcomer can consult while learning to navigate the project's technical 230 | and social environments [@zanatta2017]. Guidelines also acclimate 231 | newcomers to the norms of work and communication, particularly when 232 | items such as necessary computing tools and codes of conduct are 233 | foregrounded. 234 | 235 | ## Rule 5: Have and enforce a code of conduct. 236 | 237 | Community leaders should model the behaviors they want to encourage, but 238 | that by itself is not enough: experience shows that communities must 239 | also make norms about acceptable behavior explicit. This helps ensure 240 | that everyone---not just newcomers---will find the environment healthy 241 | and welcoming. It also sends a clear signal that the community actually 242 | *has* standards: many potential contributors will be painfully familiar 243 | with communities that don't, and are more likely to give yours a try if 244 | they believe it is not just another troll-infested chat room. Being 245 | explicit also makes the project more accessible to people from differing 246 | cultural backgrounds, as it helps them understand how expectations may 247 | differ from what they are used to. 248 | 249 | A popular way to make norms explicit is to adopt a Code of Conduct. 250 | Research on these is still in its infancy [@tourani2017], but many 251 | projects such as rOpenSci [@ropensci-coc], NumPy [@numpy-coc], and 252 | Project Jupyter [@jupyter-coc] have adopted the Contributor 253 | Covenant [@covenant] or used other frameworks such as SciPy's Code of 254 | Conduct [@scipy-coc]. 255 | 256 | A Code of Conduct is only useful if there is a clear reporting mechanism 257 | that community members trust, and if it is enforced [@aurora2019]. 258 | Projects should designate an independent party (i.e., an individual not 259 | employed by or otherwise closely connected the project) to receive and 260 | review reports. An independent party offers a degree of objectivity and 261 | can help protect reporters from hesitating to raise issues concerning 262 | project leaders out of fear of retribution or damage to their 263 | reputation. When possible, the independent party should be part of a 264 | more extensive code of conduct committee made up of several people with 265 | varied characteristics (e.g., gender identity, race, ethnicity, roles in 266 | the community). Any member of the committee implicated in the incident 267 | should be refused from reviewing the violations. 268 | 269 | Project leaders should also develop and publicize enforcement 270 | mechanisms, which may range from verbal or written warnings, limits on 271 | access to project communication avenues (e.g., Slack channels or mailing 272 | lists), or suspension or expulsion from contributing to the project. 273 | When safe for the reporter, project leaders should also publicize 274 | enforcement decisions: if this is not done, the community may come to 275 | believe that the code is meaningless. 276 | 277 | ## Rule 6: Develop forms of legitimate peripheral participation. 278 | 279 | A core concept in the theory of communities of practice is that of 280 | legitimate peripheral participation (LPP) [@lave1991; @wenger1999]. 281 | Newcomers become members of a community by participating in simple, 282 | low-risk tasks that further the goals of the community. Through these 283 | peripheral activities, newcomers become acquainted with the community's 284 | tasks, vocabulary, and governance so that they can ease into the 285 | project. 286 | 287 | In communities such as GitHub, core activities such as committing code 288 | and submitting pull requests can be socially daunting for 289 | newcomers [@steinmacher2015]. One way to encourage LPP in this case is 290 | to encourage newcomers to submit issues to a repository when they notice 291 | a bug or to join the dialog on recently submitted pull requests or 292 | issues. Another way is to have newcomers help with documentation, 293 | particularly with translation and localization, and a third (mentioned 294 | in Rule 3) is to mark some issues as suitable for newcomers. 295 | 296 | Building multiple ways of participating in a community demonstrates the 297 | variety of approaches newcomers can take to join the community. This 298 | further demonstrates that there is not just one way to make technical 299 | contributions. For example, the main form of interaction in the 300 | community on Stack Overflow is to ask a question and posting an answer, 301 | but engaging in that type of interaction can present barriers some users 302 | including an intimidating community size and fear of negative 303 | feedback [@ford2016]. Thus, it is important to provide additional forms 304 | of participation. On Stack Overflow, this is demonstrated through the 305 | ability to edit questions and answer without the restriction of 306 | reputation points. Developing a pathway to participation can decrease 307 | the presence of barriers. In studying the evolution of how content is 308 | formed in these communities [@baltes2018], newcomers can better 309 | understand the norms of a community and the best way to 310 | contribute [@ford2018]. 311 | 312 | ## Rule 7: Make it easy for newcomers to get started. 313 | 314 | One way to facilitate LPP is to make it easy for newcomers to get set up 315 | so that they can start work on contributions. Getting set up to work on 316 | a project---going from "I want to help" to "I'm able to help" to "I'm 317 | helping"---is often someone's first experience as a community 318 | participant. Any complexity or confusion at this point is therefore a 319 | significant barrier to participation [@steinmacher2014]. By treating the 320 | process of getting involved with the same care and attention you give to 321 | the product itself, you're making it clear that you value those 322 | contributors' time and effort, and forestalling reactions like 323 | this [@steinmacher2018b]: 324 | 325 | > I am still trying to build, because many errors occurred... I was 326 | > expecting to move forward, because so far I did not have time to look 327 | > at the source code... It is frustrating. 328 | 329 | This work does not just benefit newcomers: it also helps retention of 330 | existing intermittent contributors and the same work that makes your 331 | project more accessible to new contributors today will do the same for 332 | future you. Wheelchair ramps and the buttons that open heavy doors are 333 | not just used by those in wheelchairs: they are just as helpful to 334 | people with strollers or one too many bags of groceries. None of us are 335 | ever more than a sprained ankle away from desperately wanting that 336 | wheelchair ramp to be there. In that same vein, a drive failure will 337 | someday force you to download a gigabyte of data and reinstall some 338 | software, inevitably at the least convenient moment imaginable. There is 339 | therefore a lot to be gained from automating as much of your setup 340 | process you can and thoroughly documenting whatever you cannot. 341 | 342 | ## Rule 8: Use opportunities for in-person interaction---with care. 343 | 344 | Open source software projects often rely heavily on remote workers 345 | communicating via text, audio, and video. Research on face-to-face and 346 | audio/video-mediated communication is mixed with regard to their 347 | comparative effectiveness [@doherty1997; @gallupe1990; @nardi2002], but 348 | demonstrates that each form has benefits and drawbacks. In-person 349 | interaction is valuable for uninterrupted, synchronous dialog and helps 350 | to establish mutual understanding in a streamlined way [@omalley1996]. 351 | Projects can therefore benefit from engaging newcomers in in-person 352 | interaction from time to time. 353 | 354 | According to Huppenkothen and colleagues [@huppenkothen2018], newcomers 355 | may particularly benefit from events that, "...combine structured 356 | periods focused on pedagogy (often with an emphasis on statistical and 357 | computational techniques) and less structured periods devoted to hacks 358 | and creative projects, with the goal of encouraging collaboration and 359 | learning among people at various stages of their career." Combining 360 | newcomer-friendly events and activities with larger gatherings such as 361 | conferences also amortize participants' financial costs and travel time. 362 | 363 | However, potential contributors might shy away from the project if they 364 | are introverted, suffer from social anxiety, or have had bad experiences 365 | in the past in face-to-face settings. A Code of Conduct helps allay 366 | these concerns, but some newcomers may still feel uncomfortable in group 367 | settings. In this case, not going to a meetup may leave them feeling 368 | less a part of the community. 369 | 370 | Face-to-face communication also involves forms of information exchange 371 | that are not easily captured and archived for all project members to 372 | see. For example, collocated project members might hash out ideas on 373 | whiteboards, by scribbling notes, or through informal chats. Even when 374 | transcribing and/or taking photos of these is possible, important 375 | contextual information may be lost [@cherubini2007]. Decisions and 376 | changes may seem to come out of nowhere when evaluated by a 377 | non-attendee, so project leads should develop universally-accessible 378 | ways to communicate and explain the results of in-person activities. 379 | 380 | ## Rule 9: Acknowledge all contributions. 381 | 382 | People in open source sometimes joke that a programmer is someone who 383 | will do something for a laptop sticker that they would not do for a 384 | hundred dollars. The kernel of truth in this joke is that gratitude and 385 | recognition are the most powerful tools community builders have. It is 386 | therefore crucial to acknowledge newcomers' contributions and thank them 387 | for their work. Every hour that someone has given your project may be an 388 | hour taken away from their personal life or their official employment; 389 | recognize that fact and make it clear that while more hours would be 390 | welcome, you do not expect them to make unsustainable sacrifices. 391 | 392 | To ensure completeness and fairness, every project should adopt and 393 | publicize guidelines describing what constitutes a contribution, how 394 | contributions will be acknowledged, and how they will be used. Who can 395 | use the data collected by the project for what purposes, and what 396 | attribution do they have to give? How must they acknowledge the project 397 | and/or its contributors? Who holds the copyright on contributed 398 | material? Most projects now place this information in files called 399 | `LICENSE.md` and `CITATION.md`, and place a brief, readable summary in 400 | plain language in onboarding materials. 401 | 402 | ## Rule 10: Follow up on both success and failure. 403 | 404 | Once someone has carried their first contribution over the line, you and 405 | they are likely to have a better sense of what they have to offer and 406 | how the project can help them. Helping newcomers find the next problem 407 | they might want to work on or pointing them at the next thing they might 408 | enjoy reading is both helpful and supportive. In particular, encouraging 409 | them to help the next wave of newcomers is both a good way to recognize 410 | what they have learned, and an effective way to pass it on. 411 | 412 | Mentoring programs are a popular way to do this. However, their 413 | effectiveness appears mixed. [@fagerholm2014] found that, "...developers 414 | receiving deliberate onboarding support through mentoring were more 415 | active at an earlier stage than developers entering projects through 416 | conventional means." In contrast, [@labuschagne2015] found that, 417 | "...developers who join an organization through these programs are half 418 | as likely to transition into long-term community members than developers 419 | who do not use these programs... although developers who do succeed 420 | through these programs find them valuable." 421 | 422 | One explanation for this disparity is that people become members of open 423 | projects for different reasons, and hence respond to things like 424 | mentoring programs in different ways. For example, Barcomb et 425 | al. identified four types of episodic or intermittent contributors to 426 | open source projects [@barcomb2019], while Mäenpää et al. looked at how 427 | to reconcile the competing yet complementary needs of stakeholders in 428 | hybrid open/commercial projects [@maenpaa2018]. More research is needed, 429 | but as openness becomes the norm in research, doing it well becomes a 430 | core skill for every researcher. 431 | 432 | When they can, projects should also try to follow up on their failures. 433 | Why did potential contributors *not* become community members? Did they 434 | realize that the project wasn't a good fit (in which case, the overview 435 | may need an overhaul)? Was it too difficult to find a starting point or 436 | to get set up to start work (in which case information may need to be 437 | consolidated, tagged, filled in, or updated)? Or did they feel 438 | uncomfortable or under-valued (in which case the community may need to 439 | have a more difficult conversation)? The conversations with individuals 440 | should in most cases be confidential, but making the conclusions and 441 | corrective actions public is the best possible way to signal that you 442 | are serious about building the best community you can. 443 | 444 | ## Bibliography 445 | 446 | [apache-governance] Apache Software Foundation. "The Apache Software Foundation: 447 | How It Works"; Accessed March 27, 448 | 2019. https://www-us.apache.org/foundation/how-it-works.html. 449 | 450 | [guidelines] Apache Software Foundation. "Introduction to Contributing to Apache 451 | OpenOffice"; Accessed February 16, 452 | 2019. https://openoffice.apache.org/orientation/intro-contributing.html] 453 | 454 | [aurora2019] Aurora V, Gardiner M. How to Respond to Code of Conduct 455 | Reports. Version 1.1 ed. Frame Shift Consulting LLC; 2019. 456 | 457 | [baltes2018] Baltes S, Dumani L, Treude C, Diehl S. The Evolution of Stack 458 | Overflow Posts: Reconstruction and Analysis. CoRR. 2018;abs/1811.00804. 459 | 460 | [barcomb2019] Barcomb A, Stol KJ, Riehle D, Fitzgerald B. Why Do Episodic 461 | Volunteers Stay in FLOSS Communities? In: Proc. 2019 International Conference on 462 | Software Engineering (ICSE'19). ACM Press; 2019. 463 | 464 | [bezroukov1999] Bezroukov N. A Second Look at the Cathedral and the Bazaar; 465 | 1999. https://firstmonday.org/article/view/708/618. 466 | 467 | [brown2019] Brown CT. Sustaining open source: thinking about communities of 468 | effort; Accessed March 21, 469 | 2019. http://ivory.idyll.org/blog/author/c-titus-brown.html. 470 | 471 | [carpentries-bylaws] The Carpentries Bylaws; Accessed February 16, 472 | 2019. https://docs.carpentries.org/topic_folders/governance/index.html. 473 | 474 | [cherubini2007] Cherubini M, Venolia G, DeLine R, Ko AJ. Let's Go to the 475 | Whiteboard: How and Why Software Developers Use Drawings. In: Proc. 2007 476 | Conference on Human Factors in Computing Systems (CHI'07). Association for 477 | Computing Machinery (ACM); 2007. 478 | 479 | [covenant] Contributor Covenant; Accessed February 14, 480 | 2019. https://www.contributor-covenant.org/. 481 | 482 | [dagenais2010] Dagenais B, Ossher H, Bellamy RKE, Robillard MP, de Vries 483 | JP. Moving Into a New Software Project Landscape. In: Proc. 2010 International 484 | Conference on Software Engineering (ICSE'10). ACM Press; 2010. 485 | 486 | [doherty1997] Doherty-Sneddon G, O'Malley C, Garrod S, Anderson A, 487 | et al. Face-to-face and video-mediated communication: A comparison of dialogue 488 | structure and task performance. Journal of Experimental Psychology: 489 | Applied. 1997;3(2):105--125. doi:10.1037/1076-898x.3.2.105. 490 | 491 | [fagerholm2014] Fagerholm F, Guinea AS, Münch J, Borenstein J. The role of 492 | mentoring and project characteristics for onboarding in open source software 493 | projects. In: Proc. 2014 International Symposium on Empirical Software 494 | Engineering and Measurement (ESEM'14). ACM Press; 2014. 495 | 496 | [fogel2005] Fogel K. Producing Open Source Software: How to Run a Successful 497 | Free Software Project. O'Reilly Media; 2005. 498 | 499 | [ford2016] Ford D, Smith J, Guo PJ, Parnin C. Paradise Unplugged: Identifying 500 | Barriers for Female Participation on Stack Overflow. In: Proc. 2016 ACM SIGSOFT 501 | International Symposium on Foundations of Software Engineering (FSE'16). FSE 502 | 2016. ACM Press; 2016. p. 846--857. 503 | 504 | [ford2018] Ford D, Lustig K, Banks J, Parnin C. "We Don't Do That Here": How 505 | Collaborative Editing with Mentors Improves Engagement in Social Q&A 506 | Communities. In: Proc. 2018 CHI Conference on Human Factors in Computing 507 | Systems. CHI 2018; 2018. p. 608:1--608:12. 508 | 509 | [freeman1972] Freeman J. The Tyranny of Structurelessness. The Second 510 | Wave. 1972;2(1). 511 | 512 | [gallupe1990] Gallupe RB, McKeen JD. Enhancing Computer-Mediated Communication: 513 | An experimental investigation into the use of a Group Decision Support System 514 | for face-to-face versus remote meetings. Information & 515 | Management. 1990;18(1):1--13. doi:10.1016/0378-7206(90)90059-q. 516 | 517 | [github-rec] GitHub. Setting Guidelines for Repository Contributors; Accessed 518 | February 16, 519 | 2019. https://help.github.com/articles/setting-guidelines-for-repository- 520 | contributors/. 521 | 522 | [gnome-newcomers] GNOME Newcomers' Guide; Accessed February 16, 523 | 2019. https://wiki.gnome.org/Newcomers/SubmitContribution. 524 | 525 | [huppenkothen2018] Huppenkothen D, Arendt A, Hogg DW, Ram K, VanderPlas JT, 526 | Rokem A. Hack weeks as a model for data science education and 527 | collaboration. Proc National Academy of 528 | Sciences. 2018;115(36):8872--8877. doi:10.1073/pnas.1717196115. 529 | 530 | [jupyter-coc] Project Jupyter. Code of Conduct; Accessed February 14, 531 | 2019. https://github.com/jupyter/governance/blob/master/conduct/code_of_conduct.md. 532 | 533 | [labuschagne2015] Labuschagne A, Holmes R. Do Onboarding Programs Work? In: 534 | Proc. 2015 Working Conference on Mining Software Repositories 535 | (MSR'15). IEEE; 2015. 536 | 537 | [lave1991] Lave J, Wenger E. Situated Learning: Legitimate Peripheral 538 | Participation. Cambridge University Press; 1991. 539 | 540 | [libreoffice-filtered] The Document Foundation. LibreOffice Easy Hacks by Required Skill; 541 | Accessed March 21, 2019. 542 | https://wiki.documentfoundation.org/Development/EasyHacks/by_Required_Skill. 543 | 544 | [maenpaa2018] Mäenpää H, Mäkinen S, Kilamo T, Mikkonen T, Männistö T, Ritala 545 | P. Organizing for openness: six models for developer involvement in hybrid OSS 546 | projects. Journal of Internet Services and 547 | Applications. 2018;9(1). doi:10.1186/s13174-018-0088-1. 548 | 549 | [minahan1986] Minahan A. Martha's 550 | Rules. Affilia. 1986;1(2):53--56. doi:10.1177/088610998600100206. 551 | 552 | [mozilla] Mozilla Foundation. Mozilla Firefox; Accessed March 21, 553 | 2019. https://www.mozilla.org/en-US/. 554 | 555 | [my-github-resume] Coallier D. My GitHub Resume; Accessed March 21, 556 | 2019. https://resume.github.io/. 557 | 558 | [nardi2002] Nardi BA, Whittaker S. The place of face-to-face communication in 559 | distributed work. In: Hinds P, Kiesler S, editors. Distributed Work. MIT 560 | Press; 2002. p. 83--110. 561 | 562 | [numpy-coc] SciPy Community. NumPy Code of Conduct; Accessed February 14, 563 | 2019. https://www.numpy.org/devdocs/dev/conduct/code_of_conduct.html. 564 | 565 | [omalley1996] O'Malley C, Langton S, Anderson A, Doherty-Sneddon G, Bruce 566 | V. Comparison of face-to-face and video-mediated interaction. Interacting with 567 | Computers. 1996;8(2):177--192. doi:10.1016/0953-5438(96)01027-2. 568 | 569 | [openhatch] OpenHatch; Accessed March 27 2019. http://openhatch.org/. 570 | 571 | [psf-bylaws] Python Software Foundation Bylaws; Accessed February 16, 572 | 2019. https://www.python.org/psf/bylaws/. 573 | 574 | [qureshi2011] Qureshi I, Fang Y. Socialization in open source software projects: 575 | A growth mixture modeling approach. Organizational Research 576 | Methods. 2011;14(1):208--238. 577 | 578 | [raymond2001] Raymond ES. The Cathedral and the Bazaar; 2001. 579 | 580 | [ropensci-coc] rOpenSci Code of Conduct; Accessed February 14, 581 | 2019. https://ropensci.org/code-of-conduct/. 582 | 583 | [ropensci-guidelines] rOpenSci Packages: Develpoment, Maintenance, and Peer 584 | Review; Accessed February 16, 2019. https://ropensci.github.io/dev_guide/. 585 | 586 | [sarma2016] Sarma A, Chen X, Kuttal S, Dabbish L, Wang Z. Hiring in the Global 587 | Stage: Profiles of Online Contributions. In: Proc. 2016 IEEE International 588 | Conference on Global Software Engineering. ICGSE 2016. Institute of Electrical 589 | and Electronics Engineers (IEEE); 2016. 590 | 591 | [scipy-coc] SciPy Code of Conduct; Accessed February 14, 592 | 2019. https://docs.scipy.org/doc/scipy/reference/dev/conduct/code_of_conduct.html. 593 | 594 | [singh2012] Singh V. Newcomer integration and learning in technical support 595 | communities for open source software. In: Proc. 2012 ACM International 596 | Conference on Supporting Group Work - GROUP'12. ACM Press; 2012. 597 | 598 | [steinmacher2013] Steinmacher I, Wiese I, Chaves AP, Gerosa MA. Why do newcomers 599 | abandon open source software projects? In: Proc. 2013 International Workshop on 600 | Cooperative and Human Aspects of Software Engineering (CHASE'13). Institute of 601 | Electrical and Electronics Engineers (IEEE); 2013. 602 | 603 | [steinmacher2014] Steinmacher I, Wiese I, Conte T, Gerosa M, Redmiles D. The 604 | Hard Life of Open Source Software Project Newcomers. In: Proc. 2014 605 | International Workshop on Cooperative and Human Aspects of Software Engineering 606 | (CHASE'14). ACM Press; 2014. 607 | 608 | [steinmacher2015] Steinmacher I, Conte T, Gerosa MA, Redmiles D. Social Barriers 609 | Faced by Newcomers Placing Their First Contribution in Open Source Software 610 | Projects. In: Proc. 2015 ACM Conference on Computer Supported Cooperative Work 611 | & Social Computing. CSCW 2015. ACM Press; 2015. 612 | 613 | [steinmacher2016] Steinmacher I, Conte TU, Treude C, Gerosa MA. Overcoming open 614 | source project entry barriers with a portal for newcomers. In: Proc. 2016 615 | International Conference on Software Engineering (ICSE'16). ACM Press; 2016. 616 | 617 | [steinmacher2018a] Steinmacher I, Pinto G, Wiese IS, Gerosa MA. Almost There: A 618 | Study on Quasi-Contributors in Open-Source Software Projects. In: Proc. 2018 619 | International Conference on Software Engineering (ICSE'18). ACM Press; 2018. 620 | 621 | [steinmacher2018b] Steinmacher I, Treude C, Gerosa MA. Let Me In: Guidelines for 622 | the Successful Onboarding of Newcomers to Open Source Projects. IEEE 623 | Software. 2018;doi:10.1109/MS.2018.110162131. 624 | 625 | [tourani2017] Tourani P, Adams B, Serebrenik A. Code of Conduct in Open Source 626 | Projects. In: Proc. 2017 International Conference on Software Analysis, 627 | Evolution and Reengineering (SANER'17). IEEE; 2017. 628 | 629 | [wenger1999] Wenger E. Communities of Practice: Learning, Meaning, and 630 | Identity. Cambridge University Press; 1999. 631 | 632 | [zanatta2017] Zanatta AL, Steinmacher I, Machado LS, de Souza CRB, Prikladnicki 633 | R. Barriers Faced by Newcomers to Software-Crowdsourcing Projects. IEEE 634 | Software. 2017;34(2):37--43. doi:10.1109/ms.2017.32. 635 | 636 | ## Appendix: Martha's Rules 637 | 638 | 1. Anyone may put forward a proposal up to 24 hours before a meeting. 639 | Proposals must include a one-line summary, a brief description, any 640 | required background information, and a discussion of pros and cons 641 | (including alternatives). 642 | 643 | 2. Once a person has sponsored a proposal, they are responsible for it: 644 | the group may not discuss or vote on the issue unless the sponsor is 645 | present. 646 | 647 | 3. After the sponsor presents the proposal, a "sense" vote is taken 648 | prior to any discussion in which people indicate whether the like 649 | the proposal, can live with it, or are uncomfortable with it. 650 | 651 | 4. If all or most of the group likes or can live with the proposal, it 652 | moves to a formal vote with no further discussion. 653 | 654 | 5. If most of the group is uncomfortable with the proposal, it is 655 | postponed for further rework by the sponsor. 656 | 657 | 6. If some members are uncomfortable they can briefly state their 658 | objections. After ten minute of moderated discussion, the 659 | facilitator calls for a yes-or-no vote on adoption. If a majority 660 | votes "yes" the proposal is implemented. Otherwise, the proposal 661 | is returned to the sponsor for further work. 662 | -------------------------------------------------------------------------------- /10-newcomers.tex: -------------------------------------------------------------------------------- 1 | \documentclass[10pt,letterpaper]{article} 2 | 3 | %------------------------------------------------------------ 4 | 5 | \usepackage[top=0.85in,left=2.75in,footskip=0.75in]{geometry} 6 | 7 | % amsmath and amssymb packages, useful for mathematical formulas and symbols 8 | \usepackage{amsmath,amssymb} 9 | 10 | % Use adjustwidth environment to exceed column width (see example table in text) 11 | \usepackage{changepage} 12 | 13 | % Use Unicode characters when possible 14 | \usepackage[utf8x]{inputenc} 15 | 16 | % textcomp package and marvosym package for additional characters 17 | \usepackage{textcomp,marvosym} 18 | 19 | % cite package, to clean up citations in the main text. Do not remove. 20 | \usepackage{cite} 21 | 22 | % Use nameref to cite supporting information files (see Supporting Information section for more info) 23 | \usepackage{nameref,hyperref} 24 | 25 | % line numbers 26 | \usepackage[right]{lineno} 27 | 28 | % ligatures disabled 29 | \usepackage{microtype} 30 | \DisableLigatures[f]{encoding = *, family = * } 31 | 32 | % color can be used to apply background shading to table cells only 33 | \usepackage[table]{xcolor} 34 | 35 | % array package and thick rules for tables 36 | \usepackage{array} 37 | 38 | % enumerate package lets us use letters instead of numbers 39 | \usepackage{enumerate} 40 | 41 | % create "+" rule type for thick vertical lines 42 | \newcolumntype{+}{!{\vrule width 2pt}} 43 | 44 | % create \thickcline for thick horizontal lines of variable length 45 | \newlength\savedwidth 46 | \newcommand\thickcline[1]{% 47 | \noalign{\global\savedwidth\arrayrulewidth\global\arrayrulewidth 2pt}% 48 | \cline{#1}% 49 | \noalign{\vskip\arrayrulewidth}% 50 | \noalign{\global\arrayrulewidth\savedwidth}% 51 | } 52 | 53 | % \thickhline command for thick horizontal lines that span the table 54 | \newcommand\thickhline{\noalign{\global\savedwidth\arrayrulewidth\global\arrayrulewidth 2pt}% 55 | \hline 56 | \noalign{\global\arrayrulewidth\savedwidth}} 57 | 58 | \usepackage{color} 59 | 60 | % Remove comment for double spacing 61 | %\usepackage{setspace} 62 | %\doublespacing 63 | 64 | % Text layout 65 | \raggedright 66 | \setlength{\parindent}{0.5cm} 67 | \textwidth 5.25in 68 | \textheight 8.75in 69 | 70 | % Bold the 'Figure #' in the caption and separate it from the title/caption with a period 71 | % Captions will be left justified 72 | \usepackage[aboveskip=1pt,labelfont=bf,labelsep=period,justification=raggedright,singlelinecheck=off]{caption} 73 | \renewcommand{\figurename}{Fig} 74 | 75 | % Use the PLoS provided BiBTeX style 76 | \bibliographystyle{plos2015} 77 | 78 | % Remove brackets from numbering in List of References 79 | \makeatletter 80 | \renewcommand{\@biblabel}[1]{\quad#1.} 81 | \makeatother 82 | 83 | % Leave date blank 84 | \date{} 85 | 86 | % Header and Footer with logo 87 | \usepackage{lastpage,fancyhdr,graphicx} 88 | \usepackage{epstopdf} 89 | \pagestyle{myheadings} 90 | \pagestyle{fancy} 91 | \fancyhf{} 92 | \setlength{\headheight}{27.023pt} 93 | % \lhead{\includegraphics[width=2.0in]{PLOS-submission.eps}} 94 | \rfoot{\thepage/\pageref{LastPage}} 95 | \renewcommand{\footrule}{\hrule height 2pt \vspace{2mm}} 96 | \fancyheadoffset[L]{2.25in} 97 | \fancyfootoffset[L]{2.25in} 98 | \lfoot{\sf PLOS} 99 | 100 | \usepackage{tcolorbox} 101 | 102 | %------------------------------------------------------------ 103 | 104 | \newcommand{\rulemajor}[1]{\section*{#1}} 105 | \newcommand{\withurl}[2]{{#1}\footnote{{\texttt{#2}}}} 106 | 107 | \begin{document} 108 | \vspace*{0.2in} 109 | 110 | \begin{flushleft} 111 | {\Large 112 | \textbf\newline{Ten Simple Rules for Helping Newcomers Become Contributors to Open Projects} 113 | } 114 | \newline 115 | \\ 116 | {Dan Sholler}\textsuperscript{1{\ddag}}, 117 | {Igor Steinmacher}\textsuperscript{2{\ddag}}, 118 | {Denae Ford}\textsuperscript{3{\ddag}}, 119 | {Mara Averick}\textsuperscript{4{\ddag}}, 120 | {Mike Hoye}\textsuperscript{5{\ddag}}, 121 | {Greg Wilson}\textsuperscript{6{\ddag}*} 122 | \\ 123 | \bigskip 124 | \textbf{1} Berkeley Institute for Data Science, University of California Berkeley, Berkeley, CA, United States\\ 125 | \textbf{2} School of Informatics, Computing, and Cyber Systems, Northern Arizona University, Flagstaff, AZ, United States\\ 126 | \textbf{3} Department of Computer Science, North Carolina State University, Raleigh, NC, United States\\ 127 | \textbf{4} RStudio, Inc., Boston, MA, United States\\ 128 | \textbf{5} Mozilla Corporation, Toronto, ON, Canada\\ 129 | \textbf{6} RStudio, Inc., Toronto, ON, Canada\\ 130 | * Corresponding author, greg.wilson@rstudio.com. \\ 131 | \bigskip 132 | {\ddag} These authors contributed equally to this work. 133 | \end{flushleft} 134 | 135 | \section*{Introduction} 136 | 137 | To survive and thrive, 138 | a community must attract new members, 139 | retain them, 140 | and help them be productive~\cite{qureshi2011}. 141 | As openness becomes the norm in research, software development, and education, 142 | knowing how to do this has become a essential skill 143 | for principal investigators and community managers alike. 144 | A growing body of knowledge in sociology, anthropology, education, and software engineering 145 | can guide decisions about how to facilitate this. 146 | 147 | What exactly do we mean by ``community''? 148 | In the case of open source and open science, 149 | the most usual meaning is a ``community of practice''. 150 | As defined by Lave and Wenger~\cite{lave1991,wenger1999}, 151 | groups as diverse as knitting circles, oncology researchers, and web designers 152 | share three key characteristics: 153 | 154 | \begin{enumerate} 155 | 156 | \item Participants have a common product or purpose that they work on or toward. 157 | 158 | \item They are mutually engaged, \textit{i.e.}, they assist and mentor each another. 159 | 160 | \item They develop shared resources and domain knowledge. 161 | 162 | \end{enumerate} 163 | 164 | Brown~\cite{brown2019} specializes this to define a ``community of effort'' as, 165 | ``\textit{{\ldots}a community formed in pursuit of a common goal. 166 | The goal can be definite or indefinite in time, 167 | and may not be clearly defined, 168 | but it is something that (generally speaking) the community is aligned on.}'' 169 | People working to preserve coral reefs in the face of global climate change 170 | are an example of such a community. 171 | No central organization coordinates their work, 172 | but the scientists who study coral reefs, 173 | the environmentalists who work to protect them, 174 | and the citizens who support them financially and politically 175 | are aware of each other's efforts, 176 | collaborate in ad hoc ways, 177 | and are conscious of contributing toward a shared purpose. 178 | 179 | Open source software projects are also communities of effort. 180 | For example, 181 | the Mozilla Firefox~\cite{mozilla} community includes a mix of paid professionals, 182 | highly-involved volunteers, 183 | and occasional contributors who not only create software, 184 | documentation, 185 | and tutorials, 186 | but also organize events, 187 | answer questions in online forums, 188 | mentor newcomers, 189 | and advocate for open standards. 190 | 191 | Every community of effort has unique features, 192 | but they have enough in common to profit from one another's experience. 193 | The 10 rules laid out below are based on studies of such communities 194 | and on the authors' experience as members, leaders, and observers. 195 | Our focus is on small and medium-sized projects, 196 | i.e., ones that have a handful to a few hundreds participants 197 | and are a few months to a few years old, 198 | but may not (yet) have any formal legal standing 199 | such as incorporation as a non-profit. 200 | 201 | \rulemajor{Rule 1: Be welcoming.} 202 | 203 | Karl Fogel wrote~\cite{fogel2005}, 204 | ``If a project doesn't make a good first impression, newcomers may wait a long time before giving it a second chance.'' 205 | Other authors have empirically confirmed the importance of kind and polite social environments 206 | in open source projects \cite{singh2012,steinmacher2013,steinmacher2018a}. 207 | Therefore, projects should not just say that they welcome new members: 208 | they should make a proactive effort to foster positive feelings in them. 209 | One way to do this is to post a welcome message on the project's social media pages, Slack channels, forums, or email lists. 210 | Projects might also consider maintaining a dedicated ``Welcome'' channel or list, 211 | where a project lead or community manager writes a short post asking newcomers to introduce themselves. 212 | 213 | Other ways to be welcoming include 214 | offering assistance in finding ways to make an initial contribution, 215 | directing the newcomer to project members who have a similar background or skill set 216 | so as to demonstrate fit to the newcomer, 217 | and pointing the newcomer to essential project resources (e.g., the contribution guidelines). 218 | It also helps to clearly identify work items they can start with: 219 | a growing number of projects explicitly tag bugs or issues as ``suitable for newcomers'', 220 | and ask established members not to fix them 221 | in order to ensure there are suitable places for new arrivals to start work. 222 | 223 | Projects can further designate one or two members to serve as a point-of-contact for each newcomer. 224 | Doing this may reduce the newcomer's hesitancy to ask questions, 225 | particularly when they are told from the outset that there are no dumb questions in the community. 226 | 227 | \rulemajor{Rule 2: Help potential contributors evaluate if the project is a good fit.} 228 | 229 | People could contribute to many different projects; 230 | the first and most important step in being welcoming is to help them determine whether 231 | your project is a good fit for their interests and abilities. 232 | Their decision to contribute can be related to reputation or external needs, 233 | but also to a desire to learn or give back to the community. 234 | In all of these cases, 235 | the more you help newcomers understand if this is the right project for them, 236 | the more quickly they will either start contributing or look elsewhere. 237 | 238 | To do this, 239 | the project should explicitly state what the different types of skills required are. 240 | This information should be easily accessible and guide new members to the tasks they may handle. 241 | LibreOffice, 242 | for example, 243 | provides a way for developers to filter available tasks by required skills and difficulty~\cite{libreoffice-filtered}. 244 | 245 | The project should also help developers evaluate their skills, 246 | since ``basic Python skills'' means very different things to different people. 247 | Tools like My GitHub Resume~\cite{my-github-resume} and Visual Resume~\cite{sarma2016} 248 | that aggregate information from previous contributions can help with this assessment, 249 | while the now-defunct OpenHatch project~\cite{openhatch} 250 | aggregated entry-level issues from a variety of open source projects 251 | and classified them according to language and other required skills 252 | to provide a one-stop portal for finding appropriate projects. 253 | 254 | \rulemajor{Rule 3: Make governance explicit.} 255 | 256 | Raymond's ``The Cathedral and the Bazaar''~\cite{raymond2001} 257 | described an egalitarian world in which everyone could contribute equally to open projects. 258 | Two decades later, 259 | we can see how unequal and unwelcoming the supposedly egalitarian ``bazaar'' of open source can be 260 | if authority lies with those willing to shout loudest and longest. 261 | As Bezroukov pointed out~\cite{bezroukov1999}, 262 | Raymond ignored the realities of how power arises, 263 | becomes concentrated in a few hands, 264 | and is then used to perpetuate itself. 265 | 266 | Bezroukov's criticism drew on Freeman's influential essay ``The Tyranny of Structurelessness''~\cite{freeman1972}, 267 | which explained how an apparent lack of structure in organizations ``{\ldots}too often disguised an informal, 268 | unacknowledged and unaccountable leadership that was all the more pernicious because its very existence was denied.'' 269 | The solution is to make a project's governance explicit 270 | so that people know who makes which decisions. 271 | 272 | Large, well-established projects that incorporate as non-profits are required to promulgate bylaws, 273 | such as those for the Python Software Foundation~\cite{psf-bylaws}. 274 | What smaller projects should do is less well-documented, 275 | but generally falls under one of three headings~\cite{fogel2005}. 276 | The first is a ``benevolent dictator'' (often the project founder), 277 | who the community agrees has final say on important issues. 278 | This model is common in young or small projects, 279 | but is brittle, 280 | and inevitably fosters the emergence of unofficial (and hence unaccountable) de facto leaders 281 | in specific areas. 282 | 283 | The second model formalizes a consensus-building process 284 | in which the whole community can take part. 285 | One example is Martha's Rules~\cite{minahan1986}, 286 | under which anyone can put forward proposals, 287 | but those proposals are only adopted once it is clear that most people are not strongly opposed. 288 | The third model is based on elected representation. 289 | In the Carpentries~\cite{carpentries-bylaws}, 290 | for example, 291 | the electorate includes anyone who has: 292 | 293 | \begin{itemize} 294 | 295 | \item 296 | completed instructor certification in the preceding year; 297 | 298 | \item 299 | completed certification in the last two years and taught at least one workshop; 300 | 301 | \item 302 | been certified for more than two years and has taught at least twice in that time; 303 | or 304 | 305 | \item 306 | made a significant contribution to lesson development, infrastructure, or other activities 307 | as determined by the Executive Council. 308 | 309 | \end{itemize} 310 | 311 | \noindent 312 | Decisions are then made by those elected, 313 | though they may decide or be required to take some matters to a referendum vote. 314 | 315 | More complex models are possible~\cite{apache-governance}, 316 | but the most important thing is to decide on the rules well in advance of contentious issues emerging, 317 | since tempers may already be running hot by the time this point is reached. 318 | 319 | \rulemajor{Rule 4: Keep knowledge up to date and findable.} 320 | 321 | When starting to contribute to a project, 322 | newcomers must orient themselves in an unfamiliar landscape~\cite{dagenais2010}. 323 | It is therefore important to make sure that all necessary information is both accessible and findable. 324 | A single project may use wikis, files in GitHub, shared Google Docs, old tweets or Slack messages, and email archives; 325 | keeping information about a specific topic in a single place 326 | and clearly defining the purpose of each communication medium 327 | saves newcomers from having to navigate multiple unfamiliar data sources to find what they need. 328 | Doing this makes newcomers more confident and oriented~\cite{steinmacher2016}. 329 | 330 | At the same time, 331 | outdated documentation may lead newcomers to a wrong understanding of the project, 332 | which is also demotivating. 333 | While it may be hard to keep material up to date, 334 | community members should at least remove or clearly mark outdated information. 335 | Signalling the absence or staleness of material can save newcomers time 336 | and also suggest opportunities for them to make contributions that they themselves would find useful. 337 | 338 | One special case of this rule is to provide ``how to contribute'' guidelines in easy-to-find, readily-available places. 339 | Many projects follow GitHub's recommendation for placing such information in a \texttt{CONTRIBUTING.md} file~\cite{github-rec}. 340 | Other projects, 341 | such as the Apache Open Office Suite and rOpenSci, 342 | provide newcomer manuals and learning modules accessed through a web interface~\cite{apache-guidelines,ropensci-guidelines}. 343 | Still others take a more interactive approach; 344 | for example, 345 | the GNOME project's Newcomers Guide~\cite{gnome-newcomers}, walks potential contributors through the contribution pipeline: 346 | choosing a project, 347 | acquiring and installing the necessary computing tools, 348 | finding problems or choosing issues to work on, 349 | submitting changes, 350 | and following up on feedback. 351 | 352 | Such guidelines do more than just describe how to contribute. 353 | First, 354 | their mere existence can ease newcomers' hesitation 355 | about whether or not their work is sufficient and suitable for the project. 356 | Second, 357 | they provide a centralized, well-organized description of resources 358 | that a newcomer can consult while learning to navigate the project's technical and social environments~\cite{zanatta2017}. 359 | Guidelines also acclimate newcomers to the norms of work and communication, 360 | particularly when items such as necessary computing tools and codes of conduct are foregrounded. 361 | 362 | \rulemajor{Rule 5: Have and enforce a code of conduct.} 363 | 364 | Community leaders should model the behaviors they want to encourage, 365 | but that by itself is not enough: 366 | experience shows that communities must also make norms about acceptable behavior explicit. 367 | This helps ensure that everyone---not just newcomers---will find the environment healthy and welcoming. 368 | It also sends a clear signal that the community actually \textit{has} standards: 369 | many potential contributors will be painfully familiar with communities that don't, 370 | and are more likely to give yours a try if they believe 371 | it is not just another troll-infested chat room. 372 | Being explicit also makes the project more accessible to people from differing cultural backgrounds, 373 | as it helps them understand how expectations may differ from what they are used to. 374 | 375 | A popular way to make norms explicit is to adopt a Code of Conduct. 376 | Research on these is still in its infancy~\cite{tourani2017}, 377 | but many projects such as rOpenSci~\cite{ropensci-coc}, 378 | NumPy~\cite{numpy-coc}, 379 | and Project Jupyter~\cite{jupyter-coc} 380 | have adopted the Contributor Covenant~\cite{covenant} 381 | or used other frameworks such as SciPy's Code of Conduct~\cite{scipy-coc}. 382 | 383 | A Code of Conduct is only useful if there is a clear reporting mechanism that community members trust, 384 | and if it is enforced~\cite{aurora2019}. 385 | Projects should designate an independent party 386 | (i.e., an individual not employed by or otherwise closely connected the project) 387 | to receive and review reports. 388 | An independent party offers a degree of objectivity 389 | and can help protect reporters from hesitating to raise issues concerning project leaders 390 | out of fear of retribution or damage to their reputation. 391 | When possible, 392 | the independent party should be part of a more extensive code of conduct committee 393 | made up of several people with varied characteristics 394 | (e.g., gender identity, race, ethnicity, roles in the community). 395 | Any member of the committee implicated in the incident should be refused from reviewing the violations. 396 | 397 | Project leaders should also develop and publicize enforcement mechanisms, 398 | which may range from verbal or written warnings, 399 | limits on access to project communication avenues (e.g., Slack channels or mailing lists), 400 | or suspension or expulsion from contributing to the project. 401 | When safe for the reporter, 402 | project leaders should also publicize enforcement decisions: 403 | if this is not done, 404 | the community may come to believe that the code is meaningless. 405 | 406 | \rulemajor{Rule 6: Develop forms of legitimate peripheral participation.} 407 | 408 | A core concept in the theory of communities of practice is that of 409 | legitimate peripheral participation (LPP)~\cite{lave1991,wenger1999}. 410 | Newcomers become members of a community by participating in simple, low-risk tasks 411 | that further the goals of the community. 412 | Through these peripheral activities, 413 | newcomers become acquainted with the community's tasks, vocabulary, and governance 414 | so that they can ease into the project. 415 | 416 | In communities such as GitHub, 417 | core activities such as committing code and submitting pull requests can be socially daunting for newcomers~\cite{steinmacher2015}. 418 | One way to encourage LPP in this case is to encourage newcomers to submit issues to a repository when they notice a bug 419 | or to join the dialog on recently submitted pull requests or issues. 420 | Another way is to have newcomers help with documentation, 421 | particularly with translation and localization, 422 | and a third (mentioned in Rule~3) is to mark some issues as suitable for newcomers. 423 | 424 | Building multiple ways of participating in a community demonstrates the variety of approaches newcomers can take to join the community. 425 | This further demonstrates that there is not just one way to make technical contributions. 426 | For example, 427 | the main form of interaction in the community on Stack Overflow is to ask a question and posting an answer, 428 | but engaging in that type of interaction can present barriers some users 429 | including an intimidating community size and fear of negative feedback~\cite{ford2016}. 430 | Thus, it is important to provide additional forms of participation. 431 | On Stack Overflow, this is demonstrated through the ability to edit questions and answer without the restriction of reputation points. 432 | Developing a pathway to participation can decrease the presence of barriers. 433 | In studying the evolution of how content is formed in these communities~\cite{baltes2018}, 434 | newcomers can better understand the norms of a community and the best way to contribute~\cite{ford2018}. 435 | 436 | \rulemajor{Rule 7: Make it easy for newcomers to get started.} 437 | 438 | One way to facilitate LPP is to make it easy for newcomers to get set up 439 | so that they can start work on contributions. 440 | Getting set up to work on a project---going from ``I want to help'' 441 | to ``I'm able to help'' to ``I'm helping''---is often someone's first experience as a community participant. 442 | Any complexity or confusion at this point is therefore a significant barrier to participation~\cite{steinmacher2014}. 443 | By treating the process of getting involved with the same care and attention you give to the product itself, 444 | you're making it clear that you value those contributors' time and effort, 445 | and forestalling reactions like this~\cite{steinmacher2018b}: 446 | 447 | \begin{quote} 448 | I am still trying to build, because many errors occurred{\ldots} 449 | I was expecting to move forward, 450 | because so far I did not have time to look at the source code{\ldots} 451 | It is frustrating. 452 | \end{quote} 453 | 454 | This work does not just benefit newcomers: 455 | it also helps retention of existing intermittent contributors and the same work that makes your project more 456 | accessible to new contributors today will do the same for future you. 457 | Wheelchair ramps and the buttons that open heavy doors are not just used by those in wheelchairs: 458 | they are just as helpful to people with strollers or one too many bags of groceries. 459 | None of us are ever more than a sprained ankle away from desperately wanting that wheelchair ramp to be there. 460 | In that same vein, a drive failure will someday force you to download a gigabyte of data 461 | and reinstall some software, inevitably at the least convenient moment imaginable. 462 | There is therefore a lot to be gained from automating as much of your setup process you can 463 | and thoroughly documenting whatever you cannot. 464 | 465 | \rulemajor{Rule 8: Use opportunities for in-person interaction---with care.} 466 | 467 | Open source software projects often rely heavily on remote workers communicating via text, audio, and video. 468 | Research on face-to-face and audio/video-mediated communication is mixed 469 | with regard to their comparative effectiveness~\cite{doherty1997,gallupe1990,nardi2002}, 470 | but demonstrates that each form has benefits and drawbacks. 471 | In-person interaction is valuable for uninterrupted, synchronous dialog 472 | and helps to establish mutual understanding in a streamlined way~\cite{omalley1996}. 473 | Projects can therefore benefit from engaging newcomers in in-person interaction from time to time. 474 | 475 | According to Huppenkothen and colleagues~\cite{huppenkothen2018}, 476 | newcomers may particularly benefit from events that, 477 | ``{\ldots}combine structured periods focused on pedagogy 478 | (often with an emphasis on statistical and computational techniques) 479 | and less structured periods devoted to hacks and creative projects, 480 | with the goal of encouraging collaboration and learning among people at various stages of their career.'' 481 | Combining newcomer-friendly events and activities with larger gatherings such as conferences 482 | also amortize participants' financial costs and travel time. 483 | 484 | However, 485 | potential contributors might shy away from the project if they are introverted, 486 | suffer from social anxiety, 487 | or have had bad experiences in the past in face-to-face settings. 488 | A Code of Conduct helps allay these concerns, 489 | but some newcomers may still feel uncomfortable in group settings. 490 | In this case, 491 | not going to a meetup may leave them feeling less a part of the community. 492 | 493 | Face-to-face communication also involves forms of information exchange 494 | that are not easily captured and archived for all project members to see. 495 | For example, 496 | collocated project members might hash out ideas on whiteboards, 497 | by scribbling notes, 498 | or through informal chats. 499 | Even when transcribing and/or taking photos of these is possible, 500 | important contextual information may be lost~\cite{cherubini2007}. 501 | Decisions and changes may seem to come out of nowhere when evaluated by a non-attendee, 502 | so project leads should develop universally-accessible ways to communicate and explain the results of in-person activities. 503 | 504 | \rulemajor{Rule 9: Acknowledge all contributions.} 505 | 506 | People in open source sometimes joke that 507 | a programmer is someone who will do something for a laptop sticker 508 | that they would not do for a hundred dollars. 509 | The kernel of truth in this joke is that 510 | gratitude and recognition are the most powerful tools community builders have. 511 | It is therefore crucial to acknowledge newcomers' contributions and thank them for their work. 512 | Every hour that someone has given your project may be an hour taken away from their personal life 513 | or their official employment; 514 | recognize that fact 515 | and make it clear that while more hours would be welcome, 516 | you do not expect them to make unsustainable sacrifices. 517 | 518 | To ensure completeness and fairness, 519 | every project should adopt and publicize guidelines describing 520 | what constitutes a contribution, 521 | how contributions will be acknowledged, 522 | and how they will be used. 523 | Who can use the data collected by the project for what purposes, 524 | and what attribution do they have to give? 525 | How must they acknowledge the project and/or its contributors? 526 | Who holds the copyright on contributed material? 527 | Most projects now place this information in files called \texttt{LICENSE.md} and \texttt{CITATION.md}, 528 | and place a brief, readable summary in plain language in onboarding materials. 529 | 530 | \rulemajor{Rule 10: Follow up on both success and failure.} 531 | 532 | Once someone has carried their first contribution over the line, 533 | you and they are likely to have a better sense of what they have to offer 534 | and how the project can help them. 535 | Helping newcomers find the next problem they might want to work on 536 | or pointing them at the next thing they might enjoy reading 537 | is both helpful and supportive. 538 | In particular, 539 | encouraging them to help the next wave of newcomers 540 | is both a good way to recognize what they have learned, 541 | and an effective way to pass it on. 542 | 543 | Mentoring programs are a popular way to do this. 544 | However, 545 | their effectiveness appears mixed. 546 | \cite{fagerholm2014} found that, 547 | ``{\ldots}developers receiving deliberate onboarding support through mentoring 548 | were more active at an earlier stage than developers entering projects through conventional means.'' 549 | In contrast, 550 | \cite{labuschagne2015} found that, 551 | ``{\ldots}developers who join an organization through these programs 552 | are half as likely to transition into long-term community members 553 | than developers who do not use these programs{\ldots} 554 | although developers who do succeed through these programs find them valuable.'' 555 | 556 | One explanation for this disparity is that people become members of open projects for different reasons, 557 | and hence respond to things like mentoring programs in different ways. 558 | For example, 559 | Barcomb et al.\ identified four types of episodic or intermittent contributors to open source projects~\cite{barcomb2019}, 560 | while M\"{a}enp\"{a}\"{a} et al.\ looked at how to reconcile 561 | the competing yet complementary needs of stakeholders in hybrid open/commercial projects \cite{maenpaa2018}. 562 | More research is needed, 563 | but as openness becomes the norm in research, 564 | doing it well becomes a core skill for every researcher. 565 | 566 | When they can, 567 | projects should also try to follow up on their failures. 568 | Why did potential contributors \emph{not} become community members? 569 | Did they realize that the project wasn't a good fit 570 | (in which case, the overview may need an overhaul)? 571 | Was it too difficult to find a starting point or to get set up to start work 572 | (in which case information may need to be consolidated, tagged, filled in, or updated)? 573 | Or did they feel uncomfortable or under-valued 574 | (in which case the community may need to have a more difficult conversation)? 575 | The conversations with individuals should in most cases be confidential, 576 | but making the conclusions and corrective actions public 577 | is the best possible way to signal that you are serious about building the best community you can. 578 | 579 | \section*{Martha's Rules} 580 | 581 | \begin{enumerate} 582 | 583 | \item 584 | Anyone may put forward a proposal up to 24 hours before a meeting. 585 | Proposals must include a one-line summary, 586 | a brief description, 587 | any required background information, 588 | and a discussion of pros and cons (including alternatives). 589 | 590 | \item 591 | Once a person has sponsored a proposal, they are responsible for it: 592 | the group may not discuss or vote on the issue unless the sponsor is present. 593 | 594 | \item 595 | After the sponsor presents the proposal, 596 | a ``sense'' vote is taken prior to any discussion 597 | in which people indicate whether the like the proposal, 598 | can live with it, 599 | or are uncomfortable with it. 600 | 601 | \item 602 | If all or most of the group likes or can live with the proposal, 603 | it moves to a formal vote with no further discussion. 604 | 605 | \item 606 | If most of the group is uncomfortable with the proposal, 607 | it is postponed for further rework by the sponsor. 608 | 609 | \item 610 | If some members are uncomfortable they can briefly state their objections. 611 | After ten minute of moderated discussion, 612 | the facilitator calls for a yes-or-no vote on adoption. 613 | If a majority votes "yes" the proposal is implemented. 614 | Otherwise, the proposal is returned to the sponsor for further work. 615 | 616 | \end{enumerate} 617 | 618 | \subsection*{Acknowledgments} 619 | 620 | The authors are grateful to everyone who gave feedback on early versions of this paper, 621 | and particularly to Erin Robinson for her detailed, knowledgeable, and helpful critique. 622 | 623 | \begin{thebibliography}{10} 624 | 625 | \bibitem{qureshi2011} 626 | Qureshi I, Fang Y. 627 | \newblock Socialization in open source software projects: A growth mixture 628 | modeling approach. 629 | \newblock Organizational Research Methods. 2011;14(1):208--238. 630 | 631 | \bibitem{lave1991} 632 | Lave J, Wenger E. 633 | \newblock Situated Learning: Legitimate Peripheral Participation. 634 | \newblock Cambridge University Press; 1991. 635 | 636 | \bibitem{wenger1999} 637 | Wenger E. 638 | \newblock Communities of Practice: Learning, Meaning, and Identity. 639 | \newblock Cambridge University Press; 1999. 640 | 641 | \bibitem{brown2019} 642 | Brown CT. Sustaining open source: thinking about communities of effort; 643 | Accessed March 21, 2019. 644 | \newblock http://ivory.idyll.org/blog/author/c-titus-brown.html. 645 | 646 | \bibitem{mozilla} 647 | {Mozilla Foundation}. Mozilla Firefox; Accessed March 21, 2019. 648 | \newblock https://www.mozilla.org/en-US/. 649 | 650 | \bibitem{fogel2005} 651 | Fogel K. 652 | \newblock Producing Open Source Software: How to Run a Successful Free Software 653 | Project. 654 | \newblock O'Reilly Media; 2005. 655 | 656 | \bibitem{singh2012} 657 | Singh V. 658 | \newblock Newcomer integration and learning in technical support communities 659 | for open source software. 660 | \newblock In: Proc.\ 2012 {ACM} International Conference on Supporting Group 661 | Work - {GROUP'12}. {ACM} Press; 2012. 662 | 663 | \bibitem{steinmacher2013} 664 | Steinmacher I, Wiese I, Chaves AP, Gerosa MA. 665 | \newblock Why do newcomers abandon open source software projects? 666 | \newblock In: Proc.\ 2013 International Workshop on Cooperative and Human 667 | Aspects of Software Engineering ({CHASE'13}). Institute of Electrical and 668 | Electronics Engineers ({IEEE}); 2013. 669 | 670 | \bibitem{steinmacher2018a} 671 | Steinmacher I, Pinto G, Wiese IS, Gerosa MA. 672 | \newblock Almost There: A Study on Quasi-Contributors in Open-Source Software 673 | Projects. 674 | \newblock In: Proc.\ 2018 International Conference on Software Engineering 675 | ({ICSE'18}). {ACM} Press; 2018. 676 | 677 | \bibitem{libreoffice-filtered} 678 | {The Document Foundation}. LibreOffice Easy Hacks by Required Skill; Accessed 679 | March 21, 2019. 680 | \newblock 681 | https://wiki.documentfoundation.org/Development/EasyHacks/by\_Required\_Skill. 682 | 683 | \bibitem{my-github-resume} 684 | Coallier D. My GitHub Resume; Accessed March 21, 2019. 685 | \newblock https://resume.github.io/. 686 | 687 | \bibitem{sarma2016} 688 | Sarma A, Chen X, Kuttal S, Dabbish L, Wang Z. 689 | \newblock Hiring in the Global Stage: Profiles of Online Contributions. 690 | \newblock In: Proc.\ 2016 {IEEE} International Conference on Global Software 691 | Engineering. ICGSE 2016. Institute of Electrical and Electronics Engineers 692 | ({IEEE}); 2016. 693 | 694 | \bibitem{openhatch} 695 | OpenHatch; Accessed March 27 2019. 696 | \newblock http://openhatch.org/. 697 | 698 | \bibitem{raymond2001} 699 | Raymond ES. The Cathedral and the Bazaar; 2001. 700 | 701 | \bibitem{bezroukov1999} 702 | Bezroukov N. A Second Look at the Cathedral and the Bazaar; 1999. 703 | \newblock https://firstmonday.org/article/view/708/618. 704 | 705 | \bibitem{freeman1972} 706 | Freeman J. 707 | \newblock The Tyranny of Structurelessness. 708 | \newblock The Second Wave. 1972;2(1). 709 | 710 | \bibitem{psf-bylaws} 711 | Python Software Foundation Bylaws; Accessed February 16, 2019. 712 | \newblock https://www.python.org/psf/bylaws/. 713 | 714 | \bibitem{minahan1986} 715 | Minahan A. 716 | \newblock Martha's Rules. 717 | \newblock Affilia. 1986;1(2):53--56. 718 | \newblock doi:{10.1177/088610998600100206}. 719 | 720 | \bibitem{carpentries-bylaws} 721 | The Carpentries Bylaws; Accessed February 16, 2019. 722 | \newblock https://docs.carpentries.org/topic\_folders/governance/index.html. 723 | 724 | \bibitem{apache-governance} 725 | {Apache Software Foundation}. The Apache Software Foundation: How It Works; 726 | Accessed March 27, 2019. 727 | \newblock https://www-us.apache.org/foundation/how-it-works.html. 728 | 729 | \bibitem{dagenais2010} 730 | Dagenais B, Ossher H, Bellamy RKE, Robillard MP, de~Vries JP. 731 | \newblock Moving Into a New Software Project Landscape. 732 | \newblock In: Proc.\ 2010 International Conference on Software Engineering 733 | ({ICSE'10}). {ACM} Press; 2010. 734 | 735 | \bibitem{steinmacher2016} 736 | Steinmacher I, Conte TU, Treude C, Gerosa MA. 737 | \newblock Overcoming open source project entry barriers with a portal for 738 | newcomers. 739 | \newblock In: Proc.\ 2016 International Conference on Software Engineering 740 | ({ICSE'16}). {ACM} Press; 2016. 741 | 742 | \bibitem{github-rec} 743 | GitHub. Setting Guidelines for Repository Contributors; Accessed February 16, 744 | 2019. 745 | \newblock https://help.github.com/articles/setting-guidelines-for-repository- 746 | contributors/. 747 | 748 | \bibitem{apache-guidelines} 749 | {Apache Software Foundation}. Introduction to Contributing to Apache 750 | OpenOffice; Accessed February 16, 2019. 751 | \newblock https://openoffice.apache.org/orientation/intro-contributing.html. 752 | 753 | \bibitem{ropensci-guidelines} 754 | rOpenSci Packages: Develpoment, Maintenance, and Peer Review; Accessed February 755 | 16, 2019. 756 | \newblock https://ropensci.github.io/dev\_guide/. 757 | 758 | \bibitem{gnome-newcomers} 759 | GNOME Newcomers' Guide; Accessed February 16, 2019. 760 | \newblock https://wiki.gnome.org/Newcomers/SubmitContribution. 761 | 762 | \bibitem{zanatta2017} 763 | Zanatta AL, Steinmacher I, Machado LS, de~Souza CRB, Prikladnicki R. 764 | \newblock Barriers Faced by Newcomers to Software-Crowdsourcing Projects. 765 | \newblock {IEEE} Software. 2017;34(2):37--43. 766 | \newblock doi:{10.1109/ms.2017.32}. 767 | 768 | \bibitem{tourani2017} 769 | Tourani P, Adams B, Serebrenik A. 770 | \newblock Code of Conduct in Open Source Projects. 771 | \newblock In: Proc.\ 2017 International Conference on Software Analysis, 772 | Evolution and Reengineering ({SANER'17}). {IEEE}; 2017. 773 | 774 | \bibitem{ropensci-coc} 775 | rOpenSci Code of Conduct; Accessed February 14, 2019. 776 | \newblock https://ropensci.org/code-of-conduct/. 777 | 778 | \bibitem{numpy-coc} 779 | {SciPy Community}. NumPy Code of Conduct; Accessed February 14, 2019. 780 | \newblock https://www.numpy.org/devdocs/dev/conduct/code\_of\_conduct.html. 781 | 782 | \bibitem{jupyter-coc} 783 | {Project Jupyter}. Code of Conduct; Accessed February 14, 2019. 784 | \newblock 785 | https://github.com/jupyter/governance/blob/master/conduct/code\_of\_conduct.md. 786 | 787 | \bibitem{covenant} 788 | Contributor Covenant; Accessed February 14, 2019. 789 | \newblock https://www.contributor-covenant.org/. 790 | 791 | \bibitem{scipy-coc} 792 | SciPy Code of Conduct; Accessed February 14, 2019. 793 | \newblock 794 | https://docs.scipy.org/doc/scipy/reference/dev/conduct/code\_of\_conduct.html. 795 | 796 | \bibitem{aurora2019} 797 | Aurora V, Gardiner M. 798 | \newblock How to Respond to Code of Conduct Reports. 799 | \newblock Version 1.1 ed. Frame Shift Consulting LLC; 2019. 800 | 801 | \bibitem{steinmacher2015} 802 | Steinmacher I, Conte T, Gerosa MA, Redmiles D. 803 | \newblock Social Barriers Faced by Newcomers Placing Their First Contribution 804 | in Open Source Software Projects. 805 | \newblock In: Proc.\ 2015 {ACM} Conference on Computer Supported Cooperative 806 | Work {\&} Social Computing. CSCW 2015. {ACM} Press; 2015. 807 | 808 | \bibitem{ford2016} 809 | Ford D, Smith J, Guo PJ, Parnin C. 810 | \newblock Paradise Unplugged: Identifying Barriers for Female Participation on 811 | Stack Overflow. 812 | \newblock In: Proc.\ 2016 ACM SIGSOFT International Symposium on Foundations of 813 | Software Engineering ({FSE'16}). FSE 2016. {ACM} Press; 2016. p. 846--857. 814 | 815 | \bibitem{baltes2018} 816 | Baltes S, Dumani L, Treude C, Diehl S. 817 | \newblock The Evolution of Stack Overflow Posts: Reconstruction and Analysis. 818 | \newblock CoRR. 2018;abs/1811.00804. 819 | 820 | \bibitem{ford2018} 821 | Ford D, Lustig K, Banks J, Parnin C. 822 | \newblock "We Don't Do That Here": How Collaborative Editing with Mentors 823 | Improves Engagement in Social {Q\&A} Communities. 824 | \newblock In: Proc.\ 2018 CHI Conference on Human Factors in Computing Systems. 825 | CHI 2018; 2018. p. 608:1--608:12. 826 | 827 | \bibitem{steinmacher2014} 828 | Steinmacher I, Wiese I, Conte T, Gerosa M, Redmiles D. 829 | \newblock The Hard Life of Open Source Software Project Newcomers. 830 | \newblock In: Proc.\ 2014 International Workshop on Cooperative and Human 831 | Aspects of Software Engineering ({CHASE'14}). {ACM} Press; 2014. 832 | 833 | \bibitem{steinmacher2018b} 834 | Steinmacher I, Treude C, Gerosa MA. 835 | \newblock Let Me In: Guidelines for the Successful Onboarding of Newcomers to 836 | Open Source Projects. 837 | \newblock {IEEE} Software. 2018;doi:{10.1109/MS.2018.110162131}. 838 | 839 | \bibitem{doherty1997} 840 | Doherty-Sneddon G, O{\textquotesingle}Malley C, Garrod S, Anderson A, et~al. 841 | \newblock Face-to-face and video-mediated communication: A comparison of 842 | dialogue structure and task performance. 843 | \newblock Journal of Experimental Psychology: Applied. 1997;3(2):105--125. 844 | \newblock doi:{10.1037/1076-898x.3.2.105}. 845 | 846 | \bibitem{gallupe1990} 847 | Gallupe RB, McKeen JD. 848 | \newblock Enhancing Computer-Mediated Communication: An experimental 849 | investigation into the use of a Group Decision Support System for 850 | face-to-face versus remote meetings. 851 | \newblock Information {\&} Management. 1990;18(1):1--13. 852 | \newblock doi:{10.1016/0378-7206(90)90059-q}. 853 | 854 | \bibitem{nardi2002} 855 | Nardi BA, Whittaker S. 856 | \newblock The place of face-to-face communication in distributed work. 857 | \newblock In: Hinds P, Kiesler S, editors. Distributed Work. {MIT} Press; 2002. 858 | p. 83--110. 859 | 860 | \bibitem{omalley1996} 861 | O'Malley C, Langton S, Anderson A, Doherty-Sneddon G, Bruce V. 862 | \newblock Comparison of face-to-face and video-mediated interaction. 863 | \newblock Interacting with Computers. 1996;8(2):177--192. 864 | \newblock doi:{10.1016/0953-5438(96)01027-2}. 865 | 866 | \bibitem{huppenkothen2018} 867 | Huppenkothen D, Arendt A, Hogg DW, Ram K, VanderPlas JT, Rokem A. 868 | \newblock Hack weeks as a model for data science education and collaboration. 869 | \newblock Proc\ National Academy of Sciences. 2018;115(36):8872--8877. 870 | \newblock doi:{10.1073/pnas.1717196115}. 871 | 872 | \bibitem{cherubini2007} 873 | Cherubini M, Venolia G, DeLine R, Ko AJ. 874 | \newblock Let's Go to the Whiteboard: How and Why Software Developers Use 875 | Drawings. 876 | \newblock In: Proc.\ 2007 Conference on Human Factors in Computing Systems 877 | ({CHI'07}). Association for Computing Machinery ({ACM}); 2007. 878 | 879 | \bibitem{fagerholm2014} 880 | Fagerholm F, Guinea AS, M\"{u}nch J, Borenstein J. 881 | \newblock The role of mentoring and project characteristics for onboarding in 882 | open source software projects. 883 | \newblock In: Proc.\ 2014 International Symposium on Empirical Software 884 | Engineering and Measurement ({ESEM'14}). {ACM} Press; 2014. 885 | 886 | \bibitem{labuschagne2015} 887 | Labuschagne A, Holmes R. 888 | \newblock Do Onboarding Programs Work? 889 | \newblock In: Proc.\ 2015 Working Conference on Mining Software Repositories 890 | ({MSR'15}). {IEEE}; 2015. 891 | 892 | \bibitem{barcomb2019} 893 | Barcomb A, Stol KJ, Riehle D, Fitzgerald B. 894 | \newblock Why Do Episodic Volunteers Stay in FLOSS Communities? 895 | \newblock In: Proc.\ 2019 International Conference on Software Engineering 896 | ({ICSE'19}). {ACM} Press; 2019. 897 | 898 | \bibitem{maenpaa2018} 899 | M\"{a}enp\"{a}\"{a} H, M\"{a}kinen S, Kilamo T, Mikkonen T, M\"{a}nnist\"{o} T, 900 | Ritala P. 901 | \newblock Organizing for openness: six models for developer involvement in 902 | hybrid {OSS} projects. 903 | \newblock Journal of Internet Services and Applications. 2018;9(1). 904 | \newblock doi:{10.1186/s13174-018-0088-1}. 905 | 906 | \end{thebibliography} 907 | 908 | \end{document} 909 | -------------------------------------------------------------------------------- /plos2015.bst: -------------------------------------------------------------------------------- 1 | %% 2 | %% 3 | %% 4 | %% 5 | %% This `plos2015.bst' file is intended for use in PLOS submissions to 6 | %% correctly compile the bibliography according to the PLOS manuscript 7 | %% guidelines updated January 2015. 8 | %% 9 | %% 10 | %% This is derived from the `vancouver.bst' bibliographic style file (for 11 | %% LaTeX/BibTeX), generated with the docstrip utility and modified manually 12 | %% to meet the 13 | %% ``Uniform Requirements for Manuscripts Submitted to Biomedical Journals'' 14 | %% as published in N Engl J Med 1997;336:309-315. 15 | %% (also known as the Vancouver style) 16 | %% This specification may be found on the web page of the 17 | %% International Committe of Medical Journal Editors: 18 | %% 19 | %% http://www.icmje.org 20 | %% 21 | %%------------------------------------------------------------------- 22 | %% 23 | %% Copyright 2004 Folkert van der Beek 24 | %% 25 | %% This work may be distributed and/or modified under the 26 | %% conditions of the LaTeX Project Public License, either version 1.3 27 | %% of this license or (at your option) any later version. 28 | %% The latest version of this license is in 29 | %% http://www.latex-project.org/lppl.txt 30 | %% and version 1.3 or later is part of all distributions of LaTeX 31 | %% version 2005/12/01 or later. 32 | %% 33 | %% This work has the LPPL maintenance status `maintained'. 34 | %% 35 | %% The Current Maintainer of this work is Folkert van der Beek. 36 | %% 37 | %% Complaints, suggestions and comments may be sent to 38 | %% 39 | %% Folkert van der Beek 40 | %% 41 | %%------------------------------------------------------------------- 42 | %% 43 | %% This bibliography style file is intended for texts in ENGLISH 44 | %% This is a numerical citation style, and as such is standard LaTeX. 45 | %% It requires no extra package to interface to the main text. 46 | %% The form of the \bibitem entries is 47 | %% \bibitem{key}... 48 | %% Usage of \cite is as follows: 49 | %% \cite{key} ==>> [#] 50 | %% \cite[chap. 2]{key} ==>> [#, chap. 2] 51 | %% where # is a number determined by the ordering in the reference list. 52 | %% The order in the reference list is that by which the works were originally 53 | %% cited in the text, or that in the database. 54 | % 55 | %% To change the reference numbering system from [1] to 1, 56 | %% put the following code in the preamble: 57 | %% \makeatletter % Reference list option change 58 | %% \renewcommand\@biblabel[1]{#1} % from [1] to 1 59 | %% \makeatother % 60 | %% 61 | %%--------------------------------------------------------------------- 62 | 63 | %% List of all possible fields 64 | ENTRY 65 | { address 66 | assignee % for patents 67 | author 68 | booktitle % for articles in books 69 | chapter % for incollection, esp. internet documents 70 | cartographer % for maps 71 | day 72 | edition 73 | editor 74 | howpublished 75 | institution % for technical reports 76 | inventor % for patents 77 | journal 78 | key 79 | month 80 | note 81 | number 82 | organization 83 | pages 84 | part 85 | publisher 86 | school 87 | series 88 | title 89 | type 90 | volume 91 | word 92 | year 93 | eprint % urlbst 94 | doi % urlbst 95 | url % urlbst 96 | lastchecked % urlbst 97 | updated % urlbst 98 | } 99 | {} 100 | { label } 101 | %% Declaration of integer variables 102 | INTEGERS { output.state before.all mid.sentence after.sentence after.block } 103 | STRINGS { urlintro doiprefix } % urlbst... 104 | INTEGERS { hrefform addeprints adddoiresolver } 105 | % Following constants may be adjusted by hand, if desired 106 | FUNCTION {init.config.constants} 107 | { 108 | "Available from: " 'urlintro := % prefix before URL 109 | "doi:" 'doiprefix := % text prefix printed before DOI ref 110 | #0 'addeprints := % 0=no eprints; 1=include eprints 111 | #0 'adddoiresolver := % 0=no DOI resolver; 1=include it 112 | #0 'hrefform := % 0=no crossrefs; 1=hypertex xrefs; 2=hyperref refs 113 | } 114 | INTEGERS { 115 | bracket.state 116 | outside.brackets 117 | open.brackets 118 | within.brackets 119 | close.brackets 120 | } 121 | % ...urlbst to here 122 | FUNCTION {init.state.consts} 123 | { #0 'outside.brackets := % urlbst 124 | #1 'open.brackets := 125 | #2 'within.brackets := 126 | #3 'close.brackets := 127 | 128 | #0 'before.all := 129 | #1 'mid.sentence := 130 | #2 'after.sentence := 131 | #3 'after.block := 132 | } 133 | %% Declaration of string variables 134 | STRINGS { s t} 135 | 136 | % urlbst 137 | FUNCTION {output.nonnull.original} 138 | { 's := 139 | output.state mid.sentence = 140 | { ". " * write$ } 141 | { output.state after.block = 142 | { add.period$ write$ 143 | newline$ 144 | "\newblock " write$ 145 | } 146 | { output.state before.all = 147 | 'write$ 148 | { add.period$ " " * write$ } 149 | if$ 150 | } 151 | if$ 152 | mid.sentence 'output.state := 153 | } 154 | if$ 155 | s 156 | } 157 | 158 | % urlbst... 159 | FUNCTION {output.nonnull} 160 | { % Save the thing we've been asked to output 161 | 's := 162 | % If the bracket-state is close.brackets, then add a close-bracket to 163 | % what is currently at the top of the stack, and set bracket.state 164 | % to outside.brackets 165 | bracket.state close.brackets = 166 | { "]" * 167 | outside.brackets 'bracket.state := 168 | } 169 | 'skip$ 170 | if$ 171 | bracket.state outside.brackets = 172 | { % We're outside all brackets -- this is the normal situation. 173 | % Write out what's currently at the top of the stack, using the 174 | % original output.nonnull function. 175 | s 176 | output.nonnull.original 177 | } 178 | { % Still in brackets. Add open-bracket or (continuation) comma, add the 179 | % new text (in s) to the top of the stack, and move to the close-brackets 180 | % state, ready for next time (unless inbrackets resets it). If we come 181 | % into this branch, then output.state is carefully undisturbed. 182 | bracket.state open.brackets = 183 | { " [" * } 184 | { ", " * } % bracket.state will be within.brackets 185 | if$ 186 | s * 187 | close.brackets 'bracket.state := 188 | } 189 | if$ 190 | } 191 | 192 | % Call this function just before adding something which should be presented in 193 | % brackets. bracket.state is handled specially within output.nonnull. 194 | FUNCTION {inbrackets} 195 | { bracket.state close.brackets = 196 | { within.brackets 'bracket.state := } % reset the state: not open nor closed 197 | { open.brackets 'bracket.state := } 198 | if$ 199 | } 200 | 201 | FUNCTION {format.lastchecked} 202 | { lastchecked empty$ 203 | { "" } 204 | { updated empty$ 205 | { inbrackets "cited " lastchecked * } 206 | { inbrackets "updated " updated * "; cited " * lastchecked * } 207 | if$ 208 | } 209 | if$ 210 | } 211 | % ...urlbst to here 212 | 213 | FUNCTION {output} 214 | { duplicate$ empty$ 215 | 'pop$ 216 | 'output.nonnull 217 | if$ 218 | } 219 | 220 | FUNCTION {output.check} 221 | { 't := 222 | duplicate$ empty$ 223 | { pop$ "empty " t * " in " * cite$ * warning$ } 224 | 'output.nonnull 225 | if$ 226 | } 227 | 228 | FUNCTION {fin.entry} 229 | { 230 | bracket.state close.brackets = % urlbst 231 | { "]" * } 232 | 'skip$ 233 | if$ 234 | add.period$ 235 | write$ 236 | newline$ 237 | } 238 | 239 | FUNCTION {new.block} 240 | { output.state before.all = 241 | 'skip$ 242 | { after.block 'output.state := } 243 | if$ 244 | } 245 | 246 | FUNCTION {new.sentence} 247 | { output.state after.block = 248 | 'skip$ 249 | { output.state before.all = 250 | 'skip$ 251 | { after.sentence 'output.state := } 252 | if$ 253 | } 254 | if$ 255 | } 256 | 257 | FUNCTION {add.blank} 258 | { " " * before.all 'output.state := 259 | } 260 | 261 | FUNCTION {no.blank.or.punct} 262 | { "" * before.all 'output.state := 263 | } 264 | 265 | FUNCTION {add.semicolon} 266 | { 267 | ";" * 268 | no.blank.or.punct 269 | } 270 | 271 | FUNCTION {date.block} 272 | { 273 | "." * 274 | no.blank.or.punct 275 | } 276 | 277 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 278 | % LOGICAL `NOT', `AND', AND `OR' % 279 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 280 | 281 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 282 | % Logical 'not': 283 | % If the first element on the stack is A then this function 284 | % does the following: 285 | % push { #0 } 286 | % push { #1 } 287 | % So now the first 3 elements of the stack are 288 | % { #1 } { #0 } A 289 | % The first 3 are popped and subjected to 'if': 290 | % If A > 0 then { #0 } is executed, else { #1 } is executed: 291 | % if A > 0 292 | % then 0 293 | % else 1 294 | % So consider integers as logicals, where 1 = true and 0 = false, 295 | % then this does 296 | % (if A then false else true) 297 | % which is a logical 'not'. 298 | 299 | FUNCTION {not} 300 | { { #0 } 301 | { #1 } 302 | if$ 303 | } 304 | 305 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 306 | % Logical 'and': 307 | % If the first 2 elements on the stack are A B 308 | % then this function does the following: 309 | % push 'skip$ 310 | % push { pop$ #0 } 311 | % So now first 4 elements are 312 | % { pop$ #0 } 'skip$ A B 313 | % The first 3 are popped and subjected to 'if' (B is on top of 314 | % the stack): 315 | % If A > 0 then 'skip$ is executed, else { pop$ #0 } is executed: 316 | % if A > 0 317 | % then (B stays on top of stack) 318 | % else (B is popped and #0 is pushed) 319 | % So consider integers as logicals, where 1 = true and 0 = false, 320 | % then this does 321 | % (if A then B else false) 322 | % which is a logical 'and'. 323 | 324 | FUNCTION {and} 325 | { 'skip$ 326 | { pop$ #0 } 327 | if$ 328 | } 329 | 330 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 331 | % Logical 'or': 332 | % If the first 2 elements on the stack are A B 333 | % then this function does the following: 334 | % push { pop$ #1 } 335 | % push 'skip$ 336 | % So now first 4 elements are 337 | % 'skip$ { pop$ #1 } A B 338 | % The first 3 are popped and subjected to 'if' (B is on top of 339 | % the stack): 340 | % If A > 0 then { pop$ #1 } is executed, else 'skip$ is executed: 341 | % if A > 0 342 | % then (B is popped and #1 is pushed) 343 | % else (B stays on top of stack) 344 | % So consider integers as logicals, where 1 = true and 0 = false, 345 | % then this does 346 | % (if A then true else B) 347 | % which is a logical 'or'. 348 | 349 | FUNCTION {or} 350 | { { pop$ #1 } 351 | 'skip$ 352 | if$ 353 | } 354 | 355 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 356 | % GENERAL PURPOSE FUNCTIONS FOR FORMATTING % 357 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 358 | 359 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 360 | % issues warning if field is empty 361 | % call with 362 | % "field" field warning.if.empty 363 | % Note that the first field must be between quotes 364 | % because it is the fieldname for use in the warning message. 365 | % 366 | 367 | FUNCTION {warning.if.empty} 368 | { empty$ 369 | { "No " swap$ * " in " * cite$ * warning$ } 370 | { pop$ } 371 | if$ 372 | } 373 | 374 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 375 | % 376 | % encloses string in pre- and postfix string 377 | % call with 378 | % prefix postfix S enclose.check 379 | % delivers empty string if S empty 380 | % 381 | FUNCTION {enclose.check} 382 | { duplicate$ empty$ 383 | { pop$ pop$ pop$ 384 | "" 385 | } 386 | { swap$ * * } 387 | if$ 388 | } 389 | 390 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 391 | % 392 | % emphasizes top of stack 393 | % call with 394 | % string" emphasize.check 395 | % 396 | 397 | FUNCTION {emphasize.check} 398 | { "\Bem{" swap$ 399 | "}" swap$ 400 | enclose.check 401 | } 402 | 403 | 404 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 405 | % 406 | % brackets top of stack 407 | % call with 408 | % "string" bracket.check 409 | % 410 | FUNCTION {bracket.check} 411 | { "[" swap$ 412 | "]" swap$ 413 | enclose.check 414 | } 415 | 416 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 417 | % 418 | % parenthesizes top of stack 419 | % call with 420 | % "string" parenthesize 421 | % 422 | FUNCTION {parenthesize.check} 423 | { "(" swap$ 424 | ")" swap$ 425 | enclose.check 426 | } 427 | 428 | STRINGS {z} 429 | 430 | FUNCTION {remove.dots} 431 | { 'z := % expects string on top of the stack, pops the string and assigns it to variable z 432 | "" % push empty string 433 | { z empty$ not } % returns 0 if variable z is empty 434 | { z #1 #1 substring$ % push the first character of variable z 435 | z #2 global.max$ substring$ 'z := % assigns the 2nd to last character of variable z to variable z 436 | duplicate$ "\" = % pushes 1 if the last character is "\", otherwise 0 437 | { * % concatenates the last 2 literals 438 | z #1 #1 substring$ % push the first character of variable z 439 | z #2 global.max$ substring$ 'z := % assigns the 2nd to last character of variable z to variable z 440 | * % concatenates the last 2 literals, i.e. every character, even a dot, following a "\" will be printed 441 | } 442 | { duplicate$ "." = % pushes 1 if the last character is ".", otherwise 0 443 | 'pop$ % pushes the pop$ function 444 | { * } % concatenates the last 2 literals 445 | if$ % pops the last character if it is a dot, otherwise concatenates it with the string on top of the stack 446 | } 447 | if$ 448 | } 449 | while$ 450 | } 451 | 452 | INTEGERS {l} 453 | FUNCTION{string.length} 454 | { 455 | #1 'l := 456 | { duplicate$ duplicate$ #1 l substring$ = not } 457 | { l #1 + 'l := } 458 | while$ 459 | pop$ l 460 | } 461 | 462 | STRINGS {replace find text} 463 | INTEGERS {find_length} 464 | FUNCTION {find.replace} 465 | { 466 | 'replace := 467 | 'find := 468 | 'text := 469 | find string.length 'find_length := 470 | "" 471 | { text empty$ not } 472 | { text #1 find_length substring$ find = 473 | { 474 | replace * 475 | text #1 find_length + global.max$ substring$ 'text := 476 | } 477 | { text #1 #1 substring$ * 478 | text #2 global.max$ substring$ 'text := 479 | } 480 | if$ 481 | } 482 | while$ 483 | } 484 | 485 | FUNCTION {new.block.checka} 486 | { empty$ 487 | 'skip$ 488 | 'new.block 489 | if$ 490 | } 491 | 492 | FUNCTION {new.block.checkb} 493 | { empty$ 494 | swap$ empty$ 495 | and 496 | 'skip$ 497 | 'new.block 498 | if$ 499 | } 500 | 501 | FUNCTION {new.sentence.checka} 502 | { empty$ 503 | 'skip$ 504 | 'new.sentence 505 | if$ 506 | } 507 | 508 | FUNCTION {new.sentence.checkb} 509 | { empty$ 510 | swap$ empty$ 511 | and 512 | 'skip$ 513 | 'new.sentence 514 | if$ 515 | } 516 | 517 | FUNCTION {field.or.null} 518 | { duplicate$ empty$ 519 | { pop$ "" } 520 | 'skip$ 521 | if$ 522 | } 523 | 524 | FUNCTION {emphasize} 525 | { skip$ } 526 | 527 | FUNCTION {tie.or.space.prefix} 528 | { duplicate$ text.length$ #3 < 529 | { "~" } 530 | { " " } 531 | if$ 532 | swap$ 533 | } 534 | 535 | FUNCTION {capitalize} 536 | { "u" change.case$ "t" change.case$ } 537 | 538 | FUNCTION {space.word} 539 | { " " swap$ * " " * } 540 | 541 | % Here are the language-specific definitions for explicit words. 542 | % Each function has a name bbl.xxx where xxx is the English word. 543 | % The language selected here is ENGLISH 544 | 545 | FUNCTION {bbl.and} 546 | { "and"} 547 | 548 | FUNCTION {bbl.etal} 549 | { "et~al." } 550 | 551 | FUNCTION {bbl.editors} 552 | { "editors" } 553 | 554 | FUNCTION {bbl.editor} 555 | { "editor" } 556 | 557 | FUNCTION {bbl.cartographers} 558 | { "cartographers" } 559 | 560 | FUNCTION {bbl.cartographer} 561 | { "cartographer" } 562 | 563 | FUNCTION {bbl.inventors} 564 | { "inventors" } 565 | 566 | FUNCTION {bbl.inventor} 567 | { "inventor" } 568 | 569 | FUNCTION {bbl.assignees} 570 | { "assignees" } 571 | 572 | FUNCTION {bbl.assignee} 573 | { "assignee" } 574 | 575 | FUNCTION {bbl.edby} 576 | { "edited by" } 577 | 578 | FUNCTION {bbl.edition} 579 | { "ed." } 580 | 581 | FUNCTION {bbl.volume} 582 | { "vol." } 583 | 584 | FUNCTION {bbl.of} 585 | { "of" } 586 | 587 | FUNCTION {bbl.number} 588 | { "no." } 589 | 590 | FUNCTION {bbl.nr} 591 | { "no." } 592 | 593 | FUNCTION {bbl.in} 594 | { "in" } 595 | 596 | FUNCTION {bbl.pages} 597 | { " p." } 598 | 599 | FUNCTION {bbl.page} 600 | { " p." } 601 | 602 | FUNCTION {bbl.chapter} 603 | { "chap." } 604 | 605 | FUNCTION {bbl.techrep} 606 | { "Tech. Rep." } 607 | 608 | FUNCTION {bbl.mthesis} 609 | { "Master's thesis" } 610 | 611 | FUNCTION {bbl.phdthesis} 612 | { "Ph.D. thesis" } 613 | 614 | FUNCTION {bbl.first} 615 | { "1st" } 616 | 617 | FUNCTION {bbl.second} 618 | { "2nd" } 619 | 620 | FUNCTION {bbl.third} 621 | { "3rd" } 622 | 623 | FUNCTION {bbl.fourth} 624 | { "4th" } 625 | 626 | FUNCTION {bbl.fifth} 627 | { "5th" } 628 | 629 | FUNCTION {bbl.st} 630 | { "st" } 631 | 632 | FUNCTION {bbl.nd} 633 | { "nd" } 634 | 635 | FUNCTION {bbl.rd} 636 | { "rd" } 637 | 638 | FUNCTION {bbl.th} 639 | { "th" } 640 | 641 | MACRO {jan} {"Jan."} 642 | 643 | MACRO {feb} {"Feb."} 644 | 645 | MACRO {mar} {"Mar."} 646 | 647 | MACRO {apr} {"Apr."} 648 | 649 | MACRO {may} {"May"} 650 | 651 | MACRO {jun} {"Jun."} 652 | 653 | MACRO {jul} {"Jul."} 654 | 655 | MACRO {aug} {"Aug."} 656 | 657 | MACRO {sep} {"Sep."} 658 | 659 | MACRO {oct} {"Oct."} 660 | 661 | MACRO {nov} {"Nov."} 662 | 663 | MACRO {dec} {"Dec."} 664 | 665 | FUNCTION {eng.ord} 666 | { duplicate$ "1" swap$ * 667 | #-2 #1 substring$ "1" = 668 | { bbl.th * } 669 | { duplicate$ #-1 #1 substring$ 670 | duplicate$ "1" = 671 | { pop$ bbl.st * } 672 | { duplicate$ "2" = 673 | { pop$ bbl.nd * } 674 | { "3" = 675 | { bbl.rd * } 676 | { bbl.th * } 677 | if$ 678 | } 679 | if$ 680 | } 681 | if$ 682 | } 683 | if$ 684 | } 685 | 686 | FUNCTION {bibinfo.check} 687 | { swap$ 688 | duplicate$ missing$ 689 | { 690 | pop$ pop$ 691 | "" 692 | } 693 | { duplicate$ empty$ 694 | { 695 | swap$ pop$ 696 | } 697 | { swap$ 698 | pop$ 699 | } 700 | if$ 701 | } 702 | if$ 703 | } 704 | 705 | FUNCTION {bibinfo.warn} 706 | { swap$ 707 | duplicate$ missing$ 708 | { 709 | swap$ "missing " swap$ * " in " * cite$ * warning$ pop$ 710 | "" 711 | } 712 | { duplicate$ empty$ 713 | { 714 | swap$ "empty " swap$ * " in " * cite$ * warning$ 715 | } 716 | { swap$ 717 | pop$ 718 | } 719 | if$ 720 | } 721 | if$ 722 | } 723 | 724 | STRINGS { bibinfo} 725 | INTEGERS { nameptr namesleft numnames } 726 | 727 | FUNCTION {format.names} 728 | { 'bibinfo := 729 | duplicate$ empty$ 'skip$ { 730 | "." ". " find.replace 's := 731 | "" 't := 732 | #1 'nameptr := 733 | s num.names$ 'numnames := 734 | numnames 'namesleft := 735 | { namesleft #0 > } 736 | { s nameptr 737 | "{vv~}{ll}{ f{}}{ jj}" 738 | format.name$ 739 | remove.dots 740 | bibinfo bibinfo.check 741 | 't := 742 | nameptr #1 > 743 | { 744 | nameptr #6 745 | #1 + = 746 | numnames #6 747 | > and 748 | { "others" 't := 749 | #1 'namesleft := } 750 | 'skip$ 751 | if$ 752 | namesleft #1 > 753 | { ", " * t * } 754 | { 755 | "," * 756 | s nameptr "{ll}" format.name$ duplicate$ "others" = 757 | { 't := } 758 | { pop$ } 759 | if$ 760 | t "others" = 761 | { 762 | " " * bbl.etal * 763 | } 764 | { " " * t * } 765 | if$ 766 | } 767 | if$ 768 | } 769 | 't 770 | if$ 771 | nameptr #1 + 'nameptr := 772 | namesleft #1 - 'namesleft := 773 | } 774 | while$ 775 | } if$ 776 | } 777 | 778 | FUNCTION {format.names.org} 779 | { 'bibinfo := 780 | duplicate$ empty$ 'skip$ { 781 | 's := 782 | "" 't := 783 | #1 'nameptr := 784 | s num.names$ 'numnames := 785 | numnames 'namesleft := 786 | { namesleft #0 > } 787 | { s nameptr 788 | "{ff~}{vv~}{ll}" 789 | format.name$ 790 | bibinfo bibinfo.check 791 | 't := 792 | nameptr #1 > 793 | { 794 | namesleft #1 > 795 | { "; " * t * } 796 | { 797 | ";" * 798 | s nameptr "{ll}" format.name$ duplicate$ "others" = 799 | { 't := } 800 | { pop$ } 801 | if$ 802 | t "others" = 803 | { 804 | " " * bbl.etal * 805 | } 806 | { " " * t * } 807 | if$ 808 | } 809 | if$ 810 | } 811 | 't 812 | if$ 813 | nameptr #1 + 'nameptr := 814 | namesleft #1 - 'namesleft := 815 | } 816 | while$ 817 | } if$ 818 | } 819 | 820 | FUNCTION {format.names.ed} 821 | { 822 | format.names 823 | } 824 | 825 | FUNCTION {format.authors} 826 | { 827 | author "author" format.names 828 | %%"." " " "author" find.replace format.names 829 | } 830 | 831 | FUNCTION {format.organizations} 832 | { organization "organization" format.names.org 833 | } 834 | 835 | FUNCTION {get.bbl.editor} 836 | { editor num.names$ #1 > 'bbl.editors 'bbl.editor if$ } 837 | 838 | FUNCTION {get.bbl.cartographer} 839 | { cartographer num.names$ #1 > 'bbl.cartographers 'bbl.cartographer if$ } 840 | 841 | FUNCTION {get.bbl.inventor} 842 | { inventor num.names$ #1 > 'bbl.inventors 'bbl.inventor if$ } 843 | 844 | FUNCTION {get.bbl.assignee} 845 | { assignee num.names$ #1 > 'bbl.assignees 'bbl.assignee if$ } 846 | 847 | FUNCTION {format.editors} 848 | { editor "editor" format.names duplicate$ empty$ 'skip$ 849 | { 850 | "," * 851 | " " * 852 | get.bbl.editor 853 | * 854 | } 855 | if$ 856 | } 857 | 858 | FUNCTION {format.assignees} 859 | { assignee "assignee" format.names.org duplicate$ empty$ 'skip$ 860 | { 861 | "," * 862 | " " * 863 | get.bbl.assignee 864 | * 865 | } 866 | if$ 867 | } 868 | 869 | FUNCTION {format.cartographers} 870 | { cartographer "cartographer" format.names duplicate$ empty$ 'skip$ 871 | { 872 | "," * 873 | " " * 874 | get.bbl.cartographer 875 | * 876 | } 877 | if$ 878 | } 879 | 880 | FUNCTION {format.inventors} 881 | { inventor "inventor" format.names duplicate$ empty$ 'skip$ 882 | { 883 | "," * 884 | " " * 885 | get.bbl.inventor 886 | * 887 | } 888 | if$ 889 | } 890 | 891 | FUNCTION {format.note} 892 | { 893 | note empty$ 894 | { "" } 895 | { note #1 #1 substring$ 896 | duplicate$ "{" = 897 | 'skip$ 898 | { output.state mid.sentence = 899 | { "l" } 900 | { "u" } 901 | if$ 902 | change.case$ 903 | } 904 | if$ 905 | note #2 global.max$ substring$ * "note" bibinfo.check 906 | } 907 | if$ 908 | } 909 | 910 | FUNCTION {format.title} 911 | { title 912 | %%duplicate$ empty$ 'skip$ 913 | %% { "t" change.case$ } 914 | %%if$ 915 | "title" bibinfo.check 916 | } 917 | 918 | FUNCTION {format.type} 919 | { type empty$ 920 | 'skip$ 921 | { inbrackets type } 922 | %%{ add.blank "[" type * "]" * } 923 | if$ 924 | } 925 | 926 | 927 | FUNCTION {output.bibitem} 928 | { outside.brackets 'bracket.state := % urlbst 929 | newline$ 930 | "\bibitem{" write$ 931 | cite$ write$ 932 | "}" write$ 933 | newline$ 934 | "" 935 | before.all 'output.state := 936 | } 937 | 938 | FUNCTION {n.dashify} 939 | { 940 | 't := 941 | "" 942 | { t empty$ not } 943 | { t #1 #1 substring$ "-" = 944 | { t #1 #2 substring$ "--" = not 945 | { "--" * 946 | t #2 global.max$ substring$ 't := 947 | } 948 | { { t #1 #1 substring$ "-" = } 949 | { "-" * 950 | t #2 global.max$ substring$ 't := 951 | } 952 | while$ 953 | } 954 | if$ 955 | } 956 | { t #1 #1 substring$ * 957 | t #2 global.max$ substring$ 't := 958 | } 959 | if$ 960 | } 961 | while$ 962 | } 963 | 964 | FUNCTION {word.in} 965 | { bbl.in capitalize 966 | ":" * 967 | " " * } 968 | 969 | FUNCTION {format.journal.date} 970 | { 971 | "" 972 | duplicate$ empty$ 973 | year "year" bibinfo.check duplicate$ empty$ 974 | { 975 | swap$ 'skip$ 976 | { "there's a month but no year in " cite$ * warning$ } 977 | if$ 978 | * 979 | } 980 | { swap$ 'skip$ 981 | { 982 | " " * swap$ 983 | } 984 | if$ 985 | * 986 | remove.dots 987 | } 988 | if$ 989 | duplicate$ empty$ 990 | 'skip$ 991 | { 992 | before.all 'output.state := 993 | after.sentence 'output.state := 994 | } 995 | if$ 996 | } 997 | 998 | FUNCTION {format.date} 999 | { 1000 | no.blank.or.punct 1001 | ";" 1002 | duplicate$ empty$ 1003 | year "year" bibinfo.check duplicate$ empty$ 1004 | { swap$ 'skip$ 1005 | { "there's a month but no year in " cite$ * warning$ } 1006 | if$ 1007 | * 1008 | } 1009 | { swap$ 'skip$ 1010 | { 1011 | swap$ 1012 | " " * swap$ 1013 | } 1014 | if$ 1015 | * 1016 | } 1017 | if$ 1018 | } 1019 | 1020 | FUNCTION {format.btitle} 1021 | { title "title" bibinfo.check 1022 | duplicate$ empty$ 'skip$ 1023 | { 1024 | } 1025 | if$ 1026 | } 1027 | 1028 | FUNCTION {either.or.check} 1029 | { empty$ 1030 | 'pop$ 1031 | { "can't use both " swap$ * " fields in " * cite$ * warning$ } 1032 | if$ 1033 | } 1034 | 1035 | FUNCTION {format.bvolume} 1036 | { volume empty$ 1037 | { "" } 1038 | { bbl.volume volume tie.or.space.prefix 1039 | "volume" bibinfo.check * * 1040 | series "series" bibinfo.check 1041 | duplicate$ empty$ 'pop$ 1042 | { swap$ bbl.of space.word * swap$ 1043 | emphasize * } 1044 | if$ 1045 | "volume and number" number either.or.check 1046 | } 1047 | if$ 1048 | } 1049 | 1050 | FUNCTION {format.number.series} 1051 | { volume empty$ 1052 | { number empty$ 1053 | { series field.or.null } 1054 | { series empty$ 1055 | { number "number" bibinfo.check } 1056 | { output.state mid.sentence = 1057 | { bbl.number } 1058 | { bbl.number capitalize } 1059 | if$ 1060 | number tie.or.space.prefix "number" bibinfo.check * * 1061 | bbl.in space.word * 1062 | series "series" bibinfo.check * 1063 | } 1064 | if$ 1065 | } 1066 | if$ 1067 | } 1068 | { "" } 1069 | if$ 1070 | } 1071 | 1072 | FUNCTION {is.num} 1073 | { chr.to.int$ 1074 | duplicate$ "0" chr.to.int$ < not 1075 | swap$ "9" chr.to.int$ > not and 1076 | } 1077 | 1078 | FUNCTION {extract.num} 1079 | { duplicate$ 't := 1080 | "" 's := 1081 | { t empty$ not } 1082 | { t #1 #1 substring$ 1083 | t #2 global.max$ substring$ 't := 1084 | duplicate$ is.num 1085 | { s swap$ * 's := } 1086 | { pop$ "" 't := } 1087 | if$ 1088 | } 1089 | while$ 1090 | s empty$ 1091 | 'skip$ 1092 | { pop$ s } 1093 | if$ 1094 | } 1095 | 1096 | FUNCTION {convert.edition} 1097 | { extract.num "l" change.case$ 's := 1098 | s "first" = s "1" = or 1099 | { bbl.first 't := } 1100 | { s "second" = s "2" = or 1101 | { bbl.second 't := } 1102 | { s "third" = s "3" = or 1103 | { bbl.third 't := } 1104 | { s "fourth" = s "4" = or 1105 | { bbl.fourth 't := } 1106 | { s "fifth" = s "5" = or 1107 | { bbl.fifth 't := } 1108 | { s #1 #1 substring$ is.num 1109 | { s eng.ord 't := } 1110 | { edition 't := } 1111 | if$ 1112 | } 1113 | if$ 1114 | } 1115 | if$ 1116 | } 1117 | if$ 1118 | } 1119 | if$ 1120 | } 1121 | if$ 1122 | t 1123 | } 1124 | 1125 | FUNCTION {format.edition} 1126 | { edition duplicate$ empty$ 'skip$ 1127 | { 1128 | convert.edition 1129 | output.state mid.sentence = 1130 | { "l" } 1131 | { "t" } 1132 | if$ change.case$ 1133 | "edition" bibinfo.check 1134 | " " * bbl.edition * 1135 | } 1136 | if$ 1137 | } 1138 | INTEGERS { multiresult } 1139 | FUNCTION {multi.page.check} 1140 | { 't := 1141 | #0 'multiresult := 1142 | { multiresult not 1143 | t empty$ not 1144 | and 1145 | } 1146 | { t #1 #1 substring$ 1147 | duplicate$ "-" = 1148 | swap$ duplicate$ "," = 1149 | swap$ "+" = 1150 | or or 1151 | { #1 'multiresult := } 1152 | { t #2 global.max$ substring$ 't := } 1153 | if$ 1154 | } 1155 | while$ 1156 | multiresult 1157 | } 1158 | 1159 | FUNCTION {format.pages} 1160 | { pages duplicate$ empty$ 'skip$ 1161 | { duplicate$ multi.page.check 1162 | { 1163 | bbl.pages swap$ 1164 | n.dashify 1165 | } 1166 | { 1167 | bbl.page swap$ 1168 | } 1169 | if$ 1170 | tie.or.space.prefix 1171 | "pages" bibinfo.check 1172 | * * 1173 | } 1174 | if$ 1175 | } 1176 | 1177 | FUNCTION {format.journal.pages} 1178 | { pages duplicate$ empty$ 'pop$ 1179 | { swap$ duplicate$ empty$ 1180 | { pop$ pop$ format.pages } 1181 | { 1182 | ":" * 1183 | swap$ 1184 | n.dashify 1185 | "pages" bibinfo.check 1186 | * 1187 | } 1188 | if$ 1189 | } 1190 | if$ 1191 | } 1192 | 1193 | FUNCTION {format.vol.num} 1194 | { volume field.or.null 1195 | duplicate$ empty$ 'skip$ 1196 | { 1197 | "volume" bibinfo.check 1198 | } 1199 | if$ 1200 | number "number" bibinfo.check duplicate$ empty$ 'skip$ 1201 | { 1202 | swap$ duplicate$ empty$ 1203 | { "there's a number but no volume in " cite$ * warning$ } 1204 | 'skip$ 1205 | if$ 1206 | swap$ 1207 | "(" swap$ * ")" * 1208 | } 1209 | if$ * 1210 | } 1211 | 1212 | FUNCTION {format.vol.num.pages} 1213 | { volume field.or.null 1214 | duplicate$ empty$ 'skip$ 1215 | { 1216 | "volume" bibinfo.check 1217 | } 1218 | if$ 1219 | number "number" bibinfo.check duplicate$ empty$ 'skip$ 1220 | { 1221 | swap$ duplicate$ empty$ 1222 | { "there's a number but no volume in " cite$ * warning$ } 1223 | 'skip$ 1224 | if$ 1225 | swap$ 1226 | "(" swap$ * ")" * 1227 | } 1228 | if$ * 1229 | format.journal.pages 1230 | } 1231 | 1232 | FUNCTION {format.chapter.pages} 1233 | { chapter empty$ 1234 | 'format.pages 1235 | { type empty$ 1236 | { bbl.chapter } 1237 | { type "l" change.case$ 1238 | "type" bibinfo.check 1239 | } 1240 | if$ 1241 | chapter tie.or.space.prefix 1242 | "chapter" bibinfo.check 1243 | * * 1244 | pages empty$ 1245 | 'skip$ 1246 | { ", " * format.pages * } 1247 | if$ 1248 | } 1249 | if$ 1250 | } 1251 | 1252 | FUNCTION {format.booktitle} 1253 | { 1254 | booktitle "booktitle" bibinfo.check 1255 | } 1256 | 1257 | FUNCTION {format.in.ed.booktitle} 1258 | { format.booktitle duplicate$ empty$ 'skip$ 1259 | { 1260 | editor "editor" format.names.ed duplicate$ empty$ 'pop$ 1261 | { 1262 | "," * 1263 | " " * 1264 | get.bbl.editor 1265 | ". " * 1266 | * swap$ 1267 | * } 1268 | if$ 1269 | word.in swap$ * 1270 | } 1271 | if$ 1272 | } 1273 | 1274 | FUNCTION {format.in.ed.title} 1275 | { format.title duplicate$ empty$ 'skip$ 1276 | { 1277 | editor "editor" format.names.ed duplicate$ empty$ 'pop$ 1278 | { 1279 | "," * 1280 | " " * 1281 | get.bbl.editor 1282 | ". " * 1283 | * swap$ 1284 | * } 1285 | if$ 1286 | word.in swap$ * 1287 | } 1288 | if$ 1289 | } 1290 | 1291 | FUNCTION {empty.misc.check} 1292 | { author empty$ title empty$ howpublished empty$ 1293 | month empty$ year empty$ note empty$ 1294 | and and and and and 1295 | { "all relevant fields are empty in " cite$ * warning$ } 1296 | 'skip$ 1297 | if$ 1298 | } 1299 | FUNCTION {format.thesis.type} 1300 | { type duplicate$ empty$ 1301 | 'pop$ 1302 | { swap$ pop$ 1303 | "t" change.case$ "type" bibinfo.check 1304 | } 1305 | if$ 1306 | } 1307 | FUNCTION {format.tr.number} 1308 | { 1309 | number "number" bibinfo.check 1310 | %%type duplicate$ empty$ 1311 | %%{ pop$ bbl.techrep } 1312 | %%'skip$ 1313 | %%if$ 1314 | %%"type" bibinfo.check 1315 | %%swap$ duplicate$ empty$ 1316 | %%{ pop$ "t" change.case$ } 1317 | %%{ tie.or.space.prefix * * } 1318 | %%if$ 1319 | } 1320 | 1321 | FUNCTION {format.org.or.pub} 1322 | { 't := 1323 | "" 1324 | address empty$ t empty$ and 1325 | 'skip$ 1326 | { 1327 | address "address" bibinfo.check * 1328 | t empty$ 1329 | 'skip$ 1330 | { address empty$ 1331 | 'skip$ 1332 | { ": " * } 1333 | if$ 1334 | t * 1335 | } 1336 | if$ 1337 | } 1338 | if$ 1339 | } 1340 | 1341 | FUNCTION {format.publisher.address} 1342 | { publisher "publisher" bibinfo.warn format.org.or.pub 1343 | } 1344 | 1345 | FUNCTION {format.organization.address} 1346 | { organization "organization" bibinfo.check format.org.or.pub 1347 | } 1348 | 1349 | FUNCTION {format.institution.address} 1350 | { institution "institution" bibinfo.check format.org.or.pub 1351 | } 1352 | 1353 | 1354 | % urlbst... 1355 | % Functions for making hypertext links. 1356 | % In all cases, the stack has (link-text href-url) 1357 | % 1358 | % make 'null' specials 1359 | FUNCTION {make.href.null} 1360 | { 1361 | pop$ 1362 | } 1363 | % make hypertex specials 1364 | FUNCTION {make.href.hypertex} 1365 | { 1366 | "\special {html: }" * swap$ * 1368 | "\special {html:}" * 1369 | } 1370 | % make hyperref specials 1371 | FUNCTION {make.href.hyperref} 1372 | { 1373 | "\href {" swap$ * "} {" * swap$ * "}" * 1374 | } 1375 | FUNCTION {make.href} 1376 | { hrefform #2 = 1377 | 'make.href.hyperref % hrefform = 2 1378 | { hrefform #1 = 1379 | 'make.href.hypertex % hrefform = 1 1380 | 'make.href.null % hrefform = 0 (or anything else) 1381 | if$ 1382 | } 1383 | if$ 1384 | } 1385 | 1386 | FUNCTION {format.url} 1387 | { url empty$ 1388 | { "" } 1389 | { hrefform #1 = 1390 | { % special case -- add HyperTeX specials 1391 | urlintro "\url{" url * "}" * url make.href.hypertex * } 1392 | { urlintro "\url{" * url * "}" * } 1393 | if$ 1394 | } 1395 | if$ 1396 | } 1397 | 1398 | %FUNCTION {format.eprint} 1399 | %{ eprint empty$ 1400 | % { "" } 1401 | % { eprintprefix eprint * eprinturl eprint * make.href } 1402 | % if$ 1403 | %} 1404 | 1405 | FUNCTION {format.doi} 1406 | { doi empty$ 1407 | { "" } 1408 | { 1409 | new.block 1410 | "doi:{" doi * "}" * 1411 | } 1412 | if$ 1413 | } 1414 | 1415 | % Output a URL. We can't use the more normal idiom (something like 1416 | % `format.url output'), because the `inbrackets' within 1417 | % format.lastchecked applies to everything between calls to `output', 1418 | % so that `format.url format.lastchecked * output' ends up with both 1419 | % the URL and the lastchecked in brackets. 1420 | FUNCTION {output.url} 1421 | { url empty$ 1422 | 'skip$ 1423 | { new.block 1424 | format.url output 1425 | format.lastchecked output 1426 | } 1427 | if$ 1428 | } 1429 | 1430 | %FUNCTION {output.web.refs} 1431 | %{ 1432 | % new.block 1433 | % output.url 1434 | % addeprints eprint empty$ not and 1435 | % { format.eprint output.nonnull } 1436 | % 'skip$ 1437 | % if$ 1438 | % adddoiresolver doi empty$ not and 1439 | % { format.doi output.nonnull } 1440 | % 'skip$ 1441 | % if$ 1442 | % addeprints 1443 | % { eprint empty$ 1444 | % 'skip$ 1445 | % { format.eprint output.nonnull } 1446 | % if$ 1447 | % } 1448 | % 'skip$ 1449 | % if$ 1450 | %} 1451 | 1452 | 1453 | 1454 | % Webpage entry type. 1455 | % Title and url fields required; 1456 | % author, note, year, month, and lastchecked fields optional 1457 | STRINGS {database} 1458 | FUNCTION {webpage} 1459 | { output.bibitem 1460 | author empty$ 1461 | { editor empty$ 1462 | 'skip$ % author and editor both optional 1463 | { format.editors output.nonnull } 1464 | if$ 1465 | } 1466 | { editor empty$ 1467 | { format.authors output.nonnull } 1468 | { "can't use both author and editor fields in " cite$ * warning$ } 1469 | if$ 1470 | } 1471 | if$ 1472 | % author empty$ 1473 | % 'skip$ 1474 | % { format.authors output.nonnull } 1475 | % if$ 1476 | new.block 1477 | format.title "title" output.check 1478 | journal empty$ 1479 | { 1480 | format.type "type" 1481 | publisher empty$ 1482 | 'skip$ 1483 | { format.publisher.address output } 1484 | if$ 1485 | "database on the Internet" 'database := 1486 | type database = 1487 | { format.journal.date "year" output.check } 1488 | { format.date "year" output.check } 1489 | if$ 1490 | lastchecked empty$ 1491 | 'skip$ 1492 | { format.lastchecked output } 1493 | if$ 1494 | new.block 1495 | part empty$ 1496 | 'skip$ 1497 | { part output } 1498 | if$ 1499 | pages empty$ 1500 | 'skip$ 1501 | { pages bracket.check output } 1502 | if$ 1503 | } 1504 | { journal 1505 | remove.dots 1506 | "journal" bibinfo.check 1507 | "journal" output.check 1508 | format.type "type" 1509 | format.journal.date "year" output.check 1510 | lastchecked empty$ 1511 | 'skip$ 1512 | { format.lastchecked output 1513 | ";" no.blank.or.punct output 1514 | } 1515 | if$ 1516 | no.blank.or.punct format.vol.num output 1517 | pages empty$ 1518 | 'skip$ 1519 | { ":" no.blank.or.punct output 1520 | no.blank.or.punct pages bracket.check output 1521 | } 1522 | if$ 1523 | new.block 1524 | } 1525 | if$ 1526 | format.url "url" output.check 1527 | new.block 1528 | note output 1529 | fin.entry 1530 | } 1531 | % ...urlbst to here 1532 | 1533 | FUNCTION {misc} 1534 | { output.bibitem 1535 | format.authors "author" output.check 1536 | % format.editors "author and editor" output.check 1537 | format.title "title" output.check 1538 | type missing$ 1539 | { skip$ } 1540 | { format.type "type" } 1541 | %%{ inbrackets type output } 1542 | if$ 1543 | new.block 1544 | % format.publisher.address output 1545 | format.date "year" output.check 1546 | new.block 1547 | % format.note output 1548 | new.block 1549 | howpublished new.block.checka 1550 | howpublished "howpublished" bibinfo.check output 1551 | output.url % urlbst 1552 | fin.entry 1553 | empty.misc.check 1554 | } 1555 | 1556 | FUNCTION {article} 1557 | { output.bibitem 1558 | format.authors "author" output.check 1559 | organization empty$ 1560 | 'skip$ 1561 | { author empty$ 1562 | { 1563 | format.organizations "organization" output.check 1564 | } 1565 | { 1566 | "; " * 1567 | no.blank.or.punct 1568 | format.organizations "organization" output.check 1569 | } 1570 | if$ 1571 | } 1572 | if$ 1573 | new.block 1574 | format.title "title" output.check 1575 | new.block 1576 | journal 1577 | remove.dots 1578 | "journal" bibinfo.check 1579 | "journal" output.check 1580 | format.journal.date "year" output.check 1581 | add.semicolon 1582 | format.vol.num.pages output 1583 | new.block 1584 | format.doi output 1585 | new.block 1586 | % format.note output 1587 | % output.url % urlbst 1588 | fin.entry 1589 | } 1590 | 1591 | FUNCTION {book} 1592 | { output.bibitem 1593 | author empty$ 1594 | { editor empty$ 1595 | { format.organizations "organization" output.check } 1596 | { format.editors "author and editor" output.check } 1597 | if$ 1598 | } 1599 | { format.authors output.nonnull 1600 | "author and editor" editor either.or.check 1601 | } 1602 | if$ 1603 | new.block 1604 | format.btitle "title" output.check 1605 | format.bvolume output 1606 | new.block 1607 | format.edition output 1608 | new.sentence 1609 | author empty$ not 1610 | editor empty$ not 1611 | and 1612 | { format.editors "author and editor" output.check } 1613 | 'skip$ 1614 | if$ 1615 | format.number.series output 1616 | format.publisher.address output 1617 | format.date "year" output.check 1618 | new.block 1619 | % format.note output 1620 | output.url % urlbst 1621 | fin.entry 1622 | } 1623 | 1624 | FUNCTION {booklet} 1625 | { misc } 1626 | 1627 | FUNCTION {dictionary} 1628 | { output.bibitem 1629 | format.booktitle "booktitle" output.check 1630 | format.bvolume output 1631 | new.block 1632 | format.edition output 1633 | new.sentence 1634 | format.publisher.address output 1635 | format.date "year" output.check 1636 | format.btitle "title" output.check 1637 | add.semicolon 1638 | % add.blank 1639 | format.pages "pages" output.check 1640 | new.block 1641 | % format.note output 1642 | output.url % urlbst 1643 | fin.entry 1644 | } 1645 | 1646 | FUNCTION {inbook} 1647 | { output.bibitem 1648 | format.authors "author" output.check 1649 | new.block 1650 | chapter "chapter" output.check 1651 | new.block 1652 | format.in.ed.title "title" output.check 1653 | format.bvolume output 1654 | format.edition output 1655 | new.sentence 1656 | format.number.series output 1657 | format.publisher.address output 1658 | format.date "year" output.check 1659 | date.block 1660 | % add.blank 1661 | format.pages "pages" output.check 1662 | new.block 1663 | % format.note output 1664 | output.url % urlbst 1665 | fin.entry 1666 | } 1667 | 1668 | FUNCTION {incollection} 1669 | { output.bibitem 1670 | format.authors "author" output.check 1671 | new.block 1672 | format.title "title" output.check 1673 | new.block 1674 | format.in.ed.booktitle "booktitle" output.check 1675 | format.bvolume output 1676 | format.edition output 1677 | new.sentence 1678 | format.number.series output 1679 | format.publisher.address output 1680 | format.date "year" output.check 1681 | date.block 1682 | % add.blank 1683 | format.pages "pages" output.check 1684 | new.block 1685 | % format.note output 1686 | output.url % urlbst 1687 | fin.entry 1688 | } 1689 | 1690 | FUNCTION {inproceedings} 1691 | { output.bibitem 1692 | format.authors "author" output.check 1693 | new.block 1694 | format.title "title" output.check 1695 | new.block 1696 | format.in.ed.booktitle "booktitle" output.check 1697 | format.bvolume output 1698 | new.sentence 1699 | format.number.series output 1700 | publisher empty$ 1701 | { format.organization.address output } 1702 | { organization "organization" bibinfo.check output 1703 | format.publisher.address output 1704 | } 1705 | if$ 1706 | format.date "year" output.check 1707 | date.block 1708 | % add.blank 1709 | format.pages "pages" output.check 1710 | new.block 1711 | % format.note output 1712 | output.url % urlbst 1713 | fin.entry 1714 | } 1715 | 1716 | FUNCTION {conference} 1717 | {inproceedings} 1718 | 1719 | FUNCTION {manual} 1720 | {misc} 1721 | 1722 | FUNCTION {phdthesis} 1723 | { output.bibitem 1724 | format.authors "author" output.check 1725 | new.block 1726 | format.btitle 1727 | "title" output.check 1728 | format.type "type" bibinfo.check output 1729 | new.block 1730 | school "school" bibinfo.warn output 1731 | address "address" bibinfo.check output 1732 | format.date "year" output.check 1733 | new.block 1734 | % format.note output 1735 | output.url % urlbst 1736 | fin.entry 1737 | } 1738 | 1739 | FUNCTION {mastersthesis} 1740 | {phdthesis} 1741 | 1742 | FUNCTION {proceedings} 1743 | { output.bibitem 1744 | editor empty$ 1745 | { organization "organization" bibinfo.check output 1746 | } 1747 | { format.editors output.nonnull } 1748 | if$ 1749 | new.block 1750 | format.btitle "title" output.check 1751 | format.bvolume output 1752 | editor empty$ 1753 | { publisher empty$ 1754 | 'skip$ 1755 | { 1756 | new.sentence 1757 | format.number.series output 1758 | format.publisher.address output 1759 | } 1760 | if$ 1761 | } 1762 | { publisher empty$ 1763 | { 1764 | new.sentence 1765 | format.organization.address output } 1766 | { 1767 | new.sentence 1768 | organization "organization" bibinfo.check output 1769 | format.publisher.address output 1770 | } 1771 | if$ 1772 | } 1773 | if$ 1774 | format.date "year" output.check 1775 | new.block 1776 | % format.note output 1777 | output.url % urlbst 1778 | fin.entry 1779 | } 1780 | 1781 | FUNCTION {techreport} 1782 | { output.bibitem 1783 | format.authors "author" output.check 1784 | new.block 1785 | format.title 1786 | "title" output.check 1787 | new.block 1788 | format.institution.address output 1789 | format.date "year" output.check 1790 | format.tr.number output.nonnull 1791 | new.block 1792 | % format.note output 1793 | output.url % urlbst 1794 | fin.entry 1795 | } 1796 | 1797 | FUNCTION {map} 1798 | { output.bibitem 1799 | format.cartographers "cartographer" output.check 1800 | new.block 1801 | format.title 1802 | "title" output.check 1803 | format.type "type" 1804 | new.block 1805 | format.publisher.address output 1806 | format.date "year" output.check 1807 | new.block 1808 | % format.note output 1809 | output.url % urlbst 1810 | fin.entry 1811 | } 1812 | 1813 | FUNCTION {patent} 1814 | { output.bibitem 1815 | format.inventors "inventor" output.check 1816 | "; " * 1817 | no.blank.or.punct 1818 | format.assignees "assignee" output.check 1819 | new.block 1820 | format.title 1821 | "title" output.check 1822 | new.block 1823 | format.tr.number output.nonnull 1824 | format.date "year" output.check 1825 | new.block 1826 | % format.note output 1827 | output.url % urlbst 1828 | fin.entry 1829 | } 1830 | 1831 | FUNCTION {unpublished} 1832 | { output.bibitem 1833 | format.authors "author" output.check 1834 | new.block 1835 | format.title "title" output.check 1836 | format.date output 1837 | new.block 1838 | % format.note "note" output.check 1839 | output.url % urlbst 1840 | fin.entry 1841 | } 1842 | 1843 | FUNCTION {default.type} { misc } 1844 | READ 1845 | STRINGS { longest.label } 1846 | INTEGERS { number.label longest.label.width } 1847 | FUNCTION {initialize.longest.label} 1848 | { "" 'longest.label := 1849 | #1 'number.label := 1850 | #0 'longest.label.width := 1851 | } 1852 | FUNCTION {longest.label.pass} 1853 | { number.label int.to.str$ 'label := 1854 | number.label #1 + 'number.label := 1855 | label width$ longest.label.width > 1856 | { label 'longest.label := 1857 | label width$ 'longest.label.width := 1858 | } 1859 | 'skip$ 1860 | if$ 1861 | } 1862 | EXECUTE {initialize.longest.label} 1863 | ITERATE {longest.label.pass} 1864 | FUNCTION {begin.bib} 1865 | { preamble$ empty$ 1866 | 'skip$ 1867 | { preamble$ write$ newline$ } 1868 | if$ 1869 | "\begin{thebibliography}{" longest.label * "}" * 1870 | write$ newline$ 1871 | } 1872 | EXECUTE {begin.bib} 1873 | EXECUTE {init.config.constants} 1874 | EXECUTE {init.state.consts} 1875 | ITERATE {call.type$} 1876 | FUNCTION {end.bib} 1877 | { newline$ 1878 | "\end{thebibliography}" write$ newline$ 1879 | } 1880 | EXECUTE {end.bib} 1881 | %% End of customized bst file 1882 | %% 1883 | %% End of file `vancouver.bst'. 1884 | --------------------------------------------------------------------------------