Skip to content

Home

Jump to bottom
Greg Swindle edited this page Dec 11, 2017 · 5 revisions

Product logo

generator-community creates README, CODE_OF_CONDUCT, and LICENSE files based on guided questions and answers about your product. (It will so generate CONTRIBUTING documents, too.) This Wiki provides links to good examples of these files, and which generator-community has "mined" to help you create best-of-breed instructions for product consumption and collaboration.

Table of contents

1. Inner and open source success factors

Quote GitHub’s 2017 Open Source Survey showed incomplete or confusing documentation is the biggest problem for open source users. Good documentation invites people to interact with your project. Eventually, someone will open an issue or pull request. Use these interactions as opportunities to move them down the funnel.

Building Welcoming Communities. (n.d.). Retrieved August 31, 2017, from https://opensource.guide/building-community/

1.1. Usage: make it easy for someone to consume your product

In order to use your inner or open source product, people need to be able to discover and assess your product's value. Since search engines are optimized for natural human language, your product's repository should have an well-documented "home" page called the README.

1.2. Collaboration: clearly explain how to contribute

In order to contribute to your inner or open source product, people need to understand

  • How you manage collaboration,
  • The standards you uphold,
  • The conduct you expect from participants, and
  • The legal protections that your open source product provides.

1.3. Communication: document your usage and contribution guidelines

In order to build community, people need to know how you manage usage and contributions. Community standards—in the form of four documents—have emerged to help you do just that.

2. Recommended community standards for Git repositories

Add these docs

Before you launch your own open source or inner source product, add these three markdown documents to your product repository and edit their contents to match your product delivery model: they're crucial for building and sustaining a community users, contributors, and product evangelists.

2.1. README: getting started for Consumers and Contributors

Quote The README is the instruction manual that welcomes new community members to the project. It explains why the project is useful and how to get started.

Eghbal, et. al. (n.d.). How to Contribute to Open Source. Retrieved August 30, 2017, from https://opensource.guide/how-to-contribute/#anatomy-of-an-open-source-project

Boilerplate README raw markdown link README (raw markdown)
Boilerplate "read me" page README (browser-friendly)

2.1.1. Tools

  1. 💻 generator-standard-readme
  2. 💻 generator-readme
  3. 💻 generator-github-create
  4. 💻 generator-make-readme
  5. 💻 generator-badges
  6. 💻 generator-docs

2.1.2. Exemplary READMEs

2.2. CODE_OF_CONDUCT: create a positive social atmosphere for your community

Quote The code of conduct sets ground rules for participants’ behavior associated and helps to facilitate a friendly, welcoming environment. While not every project has a CODE_OF_CONDUCT file, its presence signals that this is a welcoming project to contribute to.

Eghbal, et. al. (n.d.). How to Contribute to Open Source. Retrieved August 30, 2017, from https://opensource.guide/how-to-contribute/#anatomy-of-an-open-source-project

Boilerplate "code of conduct" raw markdown link CODE_OF_CONDUCT (raw markdown)
Boilerplate "code of conduct" page CODE_OF_CONDUCT (browser-friendly)

Contributor Covenant: A Code of Conduct for Open Source Projects

2.3. CONTRIBUTING: collaboration guidelines

Quote Whereas READMEs help people use the project, contributing docs help people contribute to the project. It explains what types of contributions are needed and how the process works. While not every project has a CONTRIBUTING file, its presence signals that this is a welcoming project to contribute to.

Eghbal, et. al. (n.d.). How to Contribute to Open Source. Retrieved August 30, 2017, from https://opensource.guide/how-to-contribute/#anatomy-of-an-open-source-project

Boilerplate "contributing guidelines" raw markdown link CONTRIBUTING (raw markdown)
Boilerplate code of conduct page CONTRIBUTING (browser-friendly)

2.3.1. Tools

  1. 💻 generator-contributing
  2. 💻 weallcontribute

2.3.2. Exemplary contributing guides

  1. Atom IDE's contributing guide
  2. awesome-conributing
  3. Ember.js
  4. Guide to Idiomatic Contributing
  5. React's "How to contribute" 🌟

2.4. LICENSE: define what people can and can’t do with with open source software

Quote By definition, every open source project must have an open source license. If the project does not have a license, it is not open source.

Eghbal, et. al. (n.d.). How to Contribute to Open Source. Retrieved August 30, 2017, from https://opensource.guide/how-to-contribute/#anatomy-of-an-open-source-project

Visit "Choose an open source license" for guided license selection assistance.

2.5. Other useful repository documents

2.5.1. Issue and Pull Request templates :octocat:

Awesome Awesome GitHub Issues & PRs Templates

This is a curated list of templates that can offer inspiration for your project. An awesome template is one that informs contributors how to proceed in a very detailed or unique way.

GitHub repositories support ISSUE_TEMPLATE and PULL_REQUEST_TEMPLATE files, which allow you to customize the markdown that appears when contributors create a new Issue or Pull Request.

:octocat: Creating an issue template for your repository (ISSUE_TEMPLATE).
:octocat: Creating a pull request template for your repository (PULL_REQUEST_TEMPLATE).

2.5.2. CHANGELOGs

CHANGELOG: an empty change log to help you remember you need one 😉.

2.5.3. Checklists

PRE_RELEASE_CHECKLIST: things to validate before your ship.

2.5.4. Contributor license agreements

Individual Contributor License Agreement (CLA): A legal tool intended to avoid disputes with contributors over origin of ownership or respective rights. Unfortunately, CLAs can become barriers to contribution.

3. generator-community's product delivery roadmap

Tasks icon

Usage

Generate all recommended community docs:

# Generate all recommended community docs
$ yo community

3.1. MVP1: README sub-generator

MVP/Milestone MVP1: README

Usage

Generate a README document:

# Generate a READE document
$ yo community:readme

3.2. MVP2: Code Of Conduct sub-generator

MVP/Milestone MVP2: Code Of Conduct

Usage

Select a CODE_OF_CONDUCT document:

# Select a CODE_OF_CONDUCT document
$ yo community:code-of-conduct

3.3. MVP3: Contributing Guidelines sub-generator

MVP/Milestone MVP3: Contributing Guidelines

Usage

Generate a CONTRIBUTING document:

# Generate a CONTRIBUTING document
$ yo community:contributing

3.4. MVP4: License and CLA sub-generators

MVP/Milestone MVP4: License and CLA

Usage

Select an open source LICENSE:

# Select an open source license
$ yo community:license

3.5. MVP5: GitHub Issue and PR templates sub-generators

MVP/Milestone MVP5: GitHub Issue and PR templates

Usage

Generate a GitHub ISSUE_TEMPLATE and GitHub PULL_REQUEST_TEMPLATE:

# Generate a GitHub Issue and PR template
$ yo community:gh-templates

Only generate a GitHub ISSUE_TEMPLATE:

# Generate a GitHub Issue template
$ yo community:gh-templates --issue

Only generate a GitHub PULL_REQUEST_TEMPLATE:

# Generate a GitHub Pull Request template
$ yo community:gh-templates --pr

Creative Commons Attribution 4.0 International License This work is licensed under a Creative Commons Attribution 4.0 International License.

Graph art by icons8.

icon-home-25-image Wiki Home

Recommended community standards

  1. CODE_OF_CONDUCT
    Facilitate healthy community behavior.
  2. CONTRIBUTING
    Detailed participation guidelines.
  3. LICENSE
    Select an open source license.
  4. README
    Your repo's home page.

How-to articles

Other useful documents

To be pondered...

Clone this wiki locally