Skip to content

Latest commit

 

History

History
235 lines (157 loc) · 9.71 KB

CONTRIBUTING.md

File metadata and controls

235 lines (157 loc) · 9.71 KB
Raw

Contributing Guide

Commitizen friendly Linting: ESLint Code format: Prettier Style Guide: Airbnb Testing: Jest semantic-release: angular

Thank you for contributing to alphanumeric-encoder!

Before contributing, please take a moment to read through this document. This guide documents the standards, tooling, and processes that go into the CI/CD pipeline.

Table of Contents

Code of Conduct

Please help keep this project open and inclusive. Refer to the Code of Conduct before your first contribution.

How can I Contribute?

Submit Issues

Bug Reports: Be as detailed as possible, and fill out all information requested in the [bug report template].

For security related issues, see the security policy.

Feature Request: These are welcome, just take a moment to consider whether your idea fits within the scope and aims of this project. It is up to you to make your case of why the feature should get included. Be as detailed as possible, and fill out a [feature request].

Documentation Request: Is something unclear in the documentation or the API? Submit a [documentation change request]! Be as detailed as possible. If you have the question, chances are someone else will also who isn't willing to speak up. If you want to do it yourself, see the documentation guidelines first.

Improve Documentation

Open a new issue here.

Submit a Pull Request

Good pull requests are outstanding help. They should remain focused in scope and avoid unrelated commits.

Please [ask] before embarking on any significant pull request (e.g. implementing features, refactoring code), otherwise you risk wasting time on something that might not fit well with the project.

To submit a pull request,

  1. Fork the repository
  2. Create a branch for your edits
  3. Make sure your work follows the Follow the commits guidance

Continuous Integration/Continuous Deployment Setup

alphanumeric-encoder uses Semantic Versioning and updates automatically based on specific versioning triggers.

Local Installation

git clone https://github.com/M-Scott-Lassiter/Alphanumeric-Encoder.git
cd alphanumeric-encoder
npm install # or `yarn install`

Project Structure

A single file, index.js contains all functionality. Before submitting changes, run the build script locally then commit:

npm run build

This will lint, test, document, and format everything automatically.

Linting and Formatting

Prettier provides formatting, and ESLint does linting using the Airbnb style guide. To lint, run the following:

npm run lint

To format all files with Prettier, run:

npm run format

Testing

This project uses Jest for testing. index.test.js contains the test suite. To execute it, run:

npm run test

Documentation

API Documentation is automatically generated from JSDoc comments within the scripts. To generate, run:

npm run docs

The table of contents in this guide and the main README are automatically generated using the markdown-toc package. To generate, run:

npm run tableofcontents

Commits

This specification is inspired by and supersedes the Angular Commit Message.

If possible, make atomic commits, which means:

  • a commit should contain exactly one self-contained functional change
  • a functional change should be contained in exactly one commit
  • a commit should not create an inconsistent state (such as test errors, linting errors, partial fix, feature with documentation etc...)

A complex feature can be broken down into multiple commits as long as each one maintains a consistent state and consists of a self-contained change.

This project uses very precise rules over how Git commit messages must be formatted. This leads to easier to read commit history.

Each commit message consists of a header, a body, and a footer.

<header>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

The header is mandatory and must conform to the Commit Message Header format.

The body is mandatory for all commits except for those of type "docs". When the body is present it must be at least 20 characters long and must conform to the Commit Message Body format.

The footer is optional unless resolving issues. The Commit Message Footer format describes what the footer is used for and the structure it must have.

Commit Header Format

The header contains succinct description of the change:

  • use the imperative, present tense: "change" not "changed" nor "changes"
  • don't capitalize first letter
  • no dot (.) at the end
  • if the commit is of type revert, include reverts commit <hash>, where the hash is the SHA of the commit being reverted
<type>(<scope>): <short summary>
│ │ │
│ │ └─⫸ Summary in present tense. Not capitalized. No period at the end.
│ │
│ └─⫸ Commit Scope: api|contributing|license|readme|security
│
└─⫸ Commit Type: build|ci|docs|feat|fix|perf|refactor|revert|test

Types

Required. Must be one of the following:

  • build: Changes that affect the build system configuration, package scripts, or dev dependencies (i.e. adds/remove/modify/update)
  • ci: Changes to CI configuration files and scripts (e.g. release configs, YAML scripts)
  • docs: Documentation only changes
  • feat: Adds a new feature
  • fix: Fixes a bug in an existing feature. Also used for non-dev dependency updates.
  • perf: A code change that improves performance
  • refactor: A code change that neither fixes a bug nor adds a feature
  • revert: Revert to a commit
  • test: Add missing tests or correct existing tests

Scopes

Optional. If used, must be one of the following supported scopes:

  • api: Any documentation that helps developers or end users understand how to better employ a tool or feature
  • contributing: Contributions to this guidance or the Code of Conduct
  • license: Changes to terms or copyright status within the license. NOTE: Any wholesale change in license type MUST include a BREAKING CHANGE.
  • readme: Contributions to the main README.md
  • security: Changes that address code related security issues or security policies

Commit Body Format

Provide a plain text description of why you made this change. This is the place for you to explain your thought process, developer to developer. If helpful, include a comparison of the previous behavior with the new behavior to illustrate the change's impact.

If there are breaking changes, start the body with BREAKING CHANGE: <breaking change summary>.

Commit Footer Format

The footer identifies which issues this commit fixes. If none, leave it blank. Otherwise, use the format Resolves #<issue number>. If more than one issue is resolved, separate them with a comma.

Versioning Triggers

Pushes to the main branch causes semantic-release to check all commits since the last version for any triggers that would cause a new version. This project extends the defaults:

  • Patch
    • fix
    • perf
    • (api)
  • Version
    • feat
  • Major
    • BREAKING CHANGE

Extensions from the semantic-release default:

  • api scope (regardless of commit type) triggers a patch. This keeps API documentation for the end user as a first-class citizen without patching for any and all changes to the README or other supporting docs.