Home

generator-community will ultimately generate a README, CODE_OF_CONDUCT, CONTRIBUTING, and LICENSE file based on guided questions and answers about your product. This Wiki provides links to good examples of these files, which the generator will "mine" for copy.

Table of contents

• 1. Inner and open source success factors
  • 1.1. Usage: make it easy for someone to consume your product
  • 1.2. Collaboration: clearly explain how to contribute
  • 1.3. Communication: document your usage and contribution guidelines
• 2. Recommended community standards for Git repositories
  • 2.1. README: getting started for Consumers and Contributors
    • 2.1.1. Tools
    • 2.1.2. Exemplary READMEs
  • 2.2. CODE_OF_CONDUCT: create a positive social atmosphere for your community
  • 2.3. CONTRIBUTING: collaboration guidelines
    • 2.3.1. Tools
    • 2.3.2. Exemplary contributing guides
  • 2.4. LICENSE: define what people can and can’t do with with open source software
  • 2.5. Other useful repository documents
    • 2.5.1. Issue and Pull Request templates
    • 2.5.2. CHANGELOGs
    • 2.5.3. Checklists
    • 2.5.4. Contributor license agreements
• 3. generator-community's product delivery roadmap
  • 3.1. MVP1: README sub-generator
  • 3.2. MVP2: Code Of Conduct sub-generator
  • 3.3. MVP3: Contributing Guidelines sub-generator
  • 3.4. MVP4: License and CLA sub-generators
  • 3.5. MVP5: GitHub Issue and PR templates sub-generators

1. Inner and open source success factors

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

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

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

README.md (raw markdown)
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

• Awesome README:

  A curated list of awesome READMEs.

• Art of README

• open-source-template: A README template to encourage open-source contributions

• standard-readme: Standard Readme Style

• standard-readme Specification

• quality-docs is not specifically related to READMEs, but purports to be "A CLI tool to evaluate the quality of writing in your project's markdown files."

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

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

CODE_OF_CONDUCT.md (raw markdown)
CODE_OF_CONDUCT (browser-friendly)

Contributor Covenant: A Code of Conduct for Open Source Projects

2.3. CONTRIBUTING: collaboration guidelines

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

CONTRIBUTING.md (raw markdown)
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

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

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.md and PULL_REQUEST_TEMPLATE.md files, which allow you to customize the markdown that appears when contributors create a new Issue or Pull Request.

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

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

Usage

Generate all recommended community docs:

# Generate all recommended community docs
$ yo community-repo

3.1. MVP1: README sub-generator

MVP1: README

Usage

Generate a READE document:

# Generate a READE document
$ yo community-repo:readme

3.2. MVP2: Code Of Conduct sub-generator

MVP2: Code Of Conduct

Usage

Select a CODE_OF_CONDUCT document:

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

3.3. MVP3: Contributing Guidelines sub-generator

MVP3: Contributing Guidelines

Usage

Generate a CONTRIBUTING document:

# Generate a CONTRIBUTING document
$ yo community-repo:contributing

3.4. MVP4: License and CLA sub-generators

MVP4: License and CLA

Usage

Select an open source LICENSE:

# Select an open source license
$ yo community-repo:license

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

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-repo:gh-templates

Only generate a GitHub ISSUE_TEMPLATE:

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

Only generate a GitHub PULL_REQUEST_TEMPLATE:

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