generator-community

Generate README, CODE_OF_CONDUCT, CONTRIBUTING, and LICENSE files according to recommended community standards.

Table of contents

• 1. Overview
• 2. Installation
  • 2.1. Prerequisite software
  • 2.2. Install Yeoman and generator-community
• 3. Usage
  • 3.1. yo community:readme
    • 3.1.1. Guided assistance
    • 3.1.2. CLI automation
  • 3.2. yo community:conduct
    • 3.2.1. Guided assistance
    • 3.2.2. CLI automation
  • 3.3. yo community:contributing
  • 3.4. yo community:license
    • 3.4.1. Guided assistance
    • 3.4.2. CLI automation
  • 3.5. Update tables of contents in markdown files
• 4. npm-scripts
• 5. Semantic version and CHANGELOG
• 6. Contributing to generator-community
• 7. License

1. Overview

generator-community helps product repository maintainers follow the recommended community standards for documentation that communicates expectations, manages contributions, protects participants' legal rights, and optimizes search engine results. generator-community's simple command-line interface prompts you with simple questions in order to generate a:

1. CODE_OF_CONDUCT.md
2. CONTRIBUTING.md
3. Open source LICENSE.md
4. README.md

---

Currently, generator-community generates a:

1. .editorconfig
2. .gitattributes
3. .gitignore
4. .yo-rc.json (to store answers for your convenience)
5. CODE_OF_CONDUCT.md
6. LICENSE
7. README.md

generator-community also initializes local Git repository, if one doesn't yet exist.

Please see the Milestones for generator-community's release plan.

---

2. Installation

2.1. Prerequisite software

1. Node.js v4.1.1 or greater
2. npm (which installs with Node.js)
3. Yeoman (a command-line tool which you will install with npm, and not a manual download)
4. A package.json application manifest.

---

Verify prerequisite software...

• 2.1.2. Verify Node.js availability

  Open a Terminal and find out whether you have Node.js installed. Run:

  $ node --version
  # => v7.7.3
  

  If you do not have [Node.js][nodejs-url] installed, you will receive an error message similar to:

  # Linux or macOS
  bash: foobar: command not found
  # You need to install Node.js!
  

• 2.1.2. Install or update Node.js

  You have two options for installing Node.js.

  The easiest option is to simply download and install Node.js.

  If you feel comfortable using the command line, try one of the following version managers:

  • Node Version Manager (nvm) (for macOS and Linux Bash shells)
  • nvm-windows (for Windows)
  • nodist (for Windows)
  
  

  ℹ️ I cannot vouch for the two Windows options, so do a little homework, first.

---

2.2. Install Yeoman and generator-community

Once you've verified that you have Node.js v4.1.1. or higher installed, open a Terminal and run these two commands:

# Install Yeoman and generator-community globally
$ npm install yo --global

# 💡 The letter "i" is shorthand for "install"; -g is short for --global
$ npm i generator-community -g

3. Usage

Install all four recommended community standards (README, CODE_OF_CONDUCT, CONTRIBUTING, and a LICENSE):

# Generate README.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md, and LICENSE files
# per the recommended community community standards:

$ yo community

This will guide you with prompts to help you pre-fill the documents, e.g.,

$ yo community
? GitHub username or organization johndoe
? Product Name spike-repo
? Write a short description/value proposition The most valuable spike in the world....
? Product homepage URL https://example
? Author's name John Doe
? Author's e-mail john@doe.info
? Author's homepage https://github.com/johndoe
? Package keywords (comma to split) recommended community standards,readme,license,toc,table of contents,markdown
? Which programming language does this product use the most? Node.js (JavaScript)
? What do you use to manage dependencies (e.g., Gradle, npm, NuGet)? Leave blank if you don't know. npm
? ⦾ 📄  LICENSE: Select a license MIT
? ⦾ 📄  CODE_OF_CONDUCT: Would you like to generate a Code of Conduct? Yes
? ⦾ 📄  README: Select the sections to include in your README Overview, Configuration, Security, API, Background, License
   create package.json
   create README.md
   create .editorconfig
   create .gitattributes
   create .gitignore
   create CODE_OF_CONDUCT.md
   create LICENSE


I'm all done. Running npm install for you to install the required dependencies. If this fails, try running the command yourself.



> commitplease@2.7.10 install /Users/swindle/Projects/github/commonality/sandbox/spike-repo/node_modules/commitplease
> node install


> git-validate@2.2.2 install /Users/swindle/Projects/github/commonality/sandbox/spike-repo/node_modules/nsp/node_modules/git-validate
> node bin/install

npm WARN prepublish-on-install As of npm@5, `prepublish` scripts are deprecated.
npm WARN prepublish-on-install Use `prepare` for build steps and `prepublishOnly` for upload-only.
npm WARN prepublish-on-install See the deprecation note in `npm help scripts` for more information.

> spike-repo@0.0.0 prepublish /Users/swindle/Projects/github/commonality/sandbox/spike-repo
> nsp check

(+) No known vulnerabilities found

> spike-repo@0.0.0 prepare /Users/swindle/Projects/github/commonality/sandbox/spike-repo
> npm run lint && npm run security


> spike-repo@0.0.0 lint /Users/swindle/Projects/github/commonality/sandbox/spike-repo
> npm run lint:manifest


> spike-repo@0.0.0 lint:manifest /Users/swindle/Projects/github/commonality/sandbox/spike-repo
> fixpack

missing main
package.json fixed!

> spike-repo@0.0.0 security /Users/swindle/Projects/github/commonality/sandbox/spike-repo
> npm run security:nsp:scan


> spike-repo@0.0.0 security:nsp:scan /Users/swindle/Projects/github/commonality/sandbox/spike-repo
> nsp check

(+) No known vulnerabilities found
npm notice created a lockfile as package-lock.json. You should commit this file.
added 571 packages in 9.146s
Thank you for generating community!
✔ /README.md Updated
 Transforms run
  ⁕ TOC:excludeText=Table of contents

3.1. yo community:readme

READMEs do more than explain how to use your project. They also explain why your project matters, and what your users can do with it.

In your README, try to answer the following questions:

• What does this project do?

• Why is this project useful?

• How do I get started?

• Where can I get more help, if I need it?

Owen, K., Keepers, B., Shepherd, S., & Eghbal, N. (2017, February 17). Starting an Open Source Project. Retrieved September 13, 2017, from https://opensource.guide/starting-a-project/#writing-a-readme

3.1.1. Guided assistance

To answer prompts manually, open a Terminal and run

$ yo community:readme

The community:readme subgenerator will evaluate your product repository's manifests (e.g., package.json for Node.js products, or settings.gradle for Java products) to ensure consistency.

3.1.2. CLI automation

You can automate README.md documentation via the command line interface (CLI) (e.g., during one of your CI/CD pipelines). To view all CLI options, use the --help or -h option:

$ yo community:readme -h
Usage:
  yo community:readme [options]

  Options:
    -h,   --help                # Print the generator's options and usage
          --skip-cache          # Do not remember prompt answers                    Default: false
          --skip-install        # Do not automatically install dependencies         Default: false
          --authorName          # Author name
          --authorUrl           # Author URL
          --dependencyManager   # Tool used to install third-party libraries        Default: Unspecified
          --generateInto        # Destination directory for generated files
          --gitRemoteOriginUrl  # The URI (SSH or HTTPS) of your Git repository     Default: /
          --githubAccount       # GitHub account/organization name
          --description         # Product description
          --lang                # Product's primary programming language            Default: Unspecified
          --license             # Open source software license
          --licenseUrl          # URL to your LICENSE file                          Default: ./LICENSE
          --name                # Product name
    -a,   --includeApi          # README.md: Public API overview (optional)         Default: true
    -b,   --includeBackground   # README.md: Background section content (optional)  Default: false
    -c,   --includeConfig       # README.md: Configuration instructions (optional)  Default: false
    -o,   --includeOverview     # README.md: Overview section content (optional)    Default: false
    -s,   --includeSecurity     # README.md: Security section content (optional)    Default: false

Example:

$ yo community:readme --authorName "Jane Doe" --authorUrl "https://jdoe.example.com" \
  --githubAccount janedoeasindeer --lang JavaScript --licenseName MIT \
  --name spike-sln-community \
  --description "A spike solution to test generator-community." \
  --includeApi --includeConfig --includeSecurity

3.2. yo community:conduct

...a code of conduct helps set ground rules for behavior for your project’s participants. This is especially valuable if you’re launching an open source project for a community or company. A code of conduct empowers you to facilitate healthy, constructive community behavior, which will reduce your stress as a maintainer.

Owen, K., Keepers, B., Shepherd, S., & Eghbal, N. (2017, February 17). Starting an Open Source Project. Retrieved September 13, 2017, from https://opensource.guide/starting-a-project/#establishing-a-code-of-conduct

3.2.1. Guided assistance

To answer prompts manually, open a Terminal and run

$ yo community:conduct
? Contact email: fake@elsewhere.net
   create CODE_OF_CONDUCT.md

3.2.2. CLI automation

You can automate CODE_OF_CONDUCT.md generation via the command line interface (CLI) (e.g., during one of your CI/CD pipelines). To view all CLI options, use the --help or -h option:

$ yo community:conduct --help
Usage:
  yo community:conduct [options]

Options:
  -h,   --help          # Print the generator's options and usage
        --skip-cache    # Do not remember prompt answers             Default: false
        --skip-install  # Do not automatically install dependencies  Default: false
        --email         # Contact email
        --generateInto  # Destination directory

Example:

$ yo community:conduct --email somebody@example.com
   create CODE_OF_CONDUCT.md

3.3. yo community:contributing

A CONTRIBUTING file tells your audience how to participate in your project. For example, you might include information on:

• How to file a bug report (try using issue and pull request templates)
• How to suggest a new feature
• How to set up your environment and run tests

Owen, K., Keepers, B., Shepherd, S., & Eghbal, N. (2017, February 17). Starting an Open Source Project. Retrieved September 13, 2017, from https://opensource.guide/starting-a-project/#writing-your-contributing-guidelines

This feature will be delivered with MVP4: community:contribute.

3.4. yo community:license

An open source license guarantees that others can use, copy, modify, and contribute back to your project without repercussions. It also protects you from sticky legal situations. You must include a license when you launch an open source project.

Owen, K., Keepers, B., Shepherd, S., & Eghbal, N. (2017, February 17). Starting an Open Source Project. Retrieved September 13, 2017, from https://opensource.guide/starting-a-project/#launching-your-own-open-source-project

---

If you already have a LICENSE, the community:license subgenerator will prompt you to overwrite it, as well as your package.json.

---

3.4.1. Guided assistance

To answer prompts manually, open a Terminal and run

$ yo community:license

The community:readme subgenerator will evaluate your product repository's manifests (e.g., package.json for Node.js products, or settings.gradle for Java products) to ensure consistency.

Example:

$ yo community:license
? What's your name: Greg Swindle
? Your email (optional): greg@swindle.net
? Your website (optional):
? Which license do you want to use?
  Unlicense
  No License (Copyrighted)
  Apache 2.0
❯ MIT
  Mozilla Public License 2.0
  BSD 2-Clause (FreeBSD) License
  BSD 3-Clause (NewBSD) License

3.4.2. CLI automation

You can automatically generate a LICENSE file via the command line interface (CLI) (e.g., during one of your CI/CD pipelines). To view all CLI options, use the --help or -h option:

yo community:license -h
Usage:
  yo community:license [options]

Options:
  -h,   --help            # Print the generator's options and usage
        --skip-cache      # Do not remember prompt answers                 Default: false
        --skip-install    # Do not automatically install dependencies      Default: false
        --defaultLicense  # Default license
        --email           # Email of the license owner
        --generateInto    # Destination directory of the generated files
        --license         # Enter an SPDX license name
        --name            # Name of the license owner
        --output          # Set the output file for the generated license  Default: LICENSE
        --website         # Website of the license owner
        --year            # Year(s) to include on the license              Default: 2017

3.5. Update tables of contents in markdown files

yo community installs an npm-script that will help keep your documents' table of contents up-to-date. To automatically update your markdown files' tables of contents:

• Add the following comments to your markdown file(s):

  <!-- ⛔️ AUTO-GENERATED-CONTENT:START (TOC:excludeText=Table of contents) -->
  This text will be replaced by a table of contents 😏 .
  <!-- ⛔️ AUTO-GENERATED-CONTENT:END -->

• Open a Terminal and run:

  $ npm run docs:toc

For more information, visit DavidWells/markdown-magic.

4. npm-scripts

Software modules often have funky, irrelative names; therefore, we prefix custom tasks by their responsibility and purpose.

Prefix	Definition
build*	Source code distribution tasks.
docs*	API documentation and automation tasks.
lint*	Code style, standards, and vulnerabilty assessments (as well as fixes, if available).
release	Bump the product's semver, update docs, commit, and publish to the npm registry.
security*	Security vulnerabilty checks.

The following CLI npm-scripts are available to you (assuming you're human, gentle reader) and CI-services.

Script	Description
docs	npm run docs:scripts && npm run docs:toc
docs:toc	md-magic --path '**/*.md' --ignore 'node_modules'
lint	npm run lint:node-version && npm run lint:js && npm run lint:manifest
lint:js	eslint ./generators/**/*.js ./__tests__/**/*.js --fix
lint:manifest	fixpack
lint:node-version	check-node-version --package
prepublish	npm run security
release	standard-version
security	npm run security:nsp:scan
security:nsp:scan	nsp check
pretest	npm prune && npm run lint
test	jest --forceExit --config=jest.config.json
posttest	npm run security

5. Semantic version and CHANGELOG

The latest version of commonality/generator-community is 0.0.0. View the CHANGELOG for details.

6. Contributing to generator-community

We welcome contributors with Pull Requests!

Contributions in the form of GitHub pull requests are welcome. Before embarking on a significant change, please adhere to the following guidelines:

1. Read the Code of Conduct.
2. Create an issue to discuss the proposed change and ensure that it is likely to be merged:
   • Report a defect (aka "bug");
   • Request a new feature;
   • Volunteer for an available issue.
3. Follow Contributing to generator-community's coding conventions and Git workflow if you're willing and able to program (or want to learn how).

7. License

MIT © Greg Swindle.

Third-party software licenses for `generator-community (read the NOTICE file for a detailed report):

---