Generate
README,CODE_OF_CONDUCT,CONTRIBUTING, andLICENSEfiles according to recommended community standards.
- 1. Overview
- 2. Installation
- 3. Usage
- 4.
npm-scripts - 5. Semantic version and
CHANGELOG - 6. Contributing to
generator-community - 7. License
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:
CODE_OF_CONDUCT.mdCONTRIBUTING.md- Open source
LICENSE.md README.md
Currently, generator-community generates a:
.editorconfig.gitattributes.gitignore.yo-rc.json(to store answers for your convenience)CODE_OF_CONDUCT.mdLICENSEREADME.md
generator-community also initializes local Git repository, if one doesn't yet exist.
Please see the Milestones for generator-community's release plan.
- Node.js v4.1.1 or greater
- npm (which installs with Node.js)
- Yeoman (a command-line tool which you will install with npm, and not a manual download)
- A
package.jsonapplication manifest.
Verify prerequisite software...
-
Open a Terminal and find out whether you have Node.js installed. Run:
$ node --version # => v7.7.3If 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! -
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.
- Node Version Manager (
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 -gInstall 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 communityThis 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
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
To answer prompts manually, open a Terminal and run
$ yo community:readmeThe 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.
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: falseExample:
$ 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
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
To answer prompts manually, open a Terminal and run
$ yo community:conduct
? Contact email: fake@elsewhere.net
create CODE_OF_CONDUCT.mdYou 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 directoryExample:
$ yo community:conduct --email somebody@example.com
create CODE_OF_CONDUCT.md
- 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.
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.
To answer prompts manually, open a Terminal and run
$ yo community:licenseThe 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) LicenseYou 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
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.
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 |
The latest version of commonality/generator-community is 0.0.0. View the CHANGELOG for details.
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:
- Read the Code of Conduct.
- 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.
- Follow Contributing to
generator-community's coding conventions and Git workflow if you're willing and able to program (or want to learn how).
MIT © Greg Swindle.
Third-party software licenses for `generator-community (read the NOTICE file for a detailed report):
