From 0458730b14ed938c872b52894eb7bedd47a845d8 Mon Sep 17 00:00:00 2001 From: Nelly Kiboi Date: Tue, 18 Feb 2020 22:53:50 +0000 Subject: [PATCH] chore(contributing): update contributing guidelines (#2) --- .travis.yml | 4 ++ CONTRIBUTING.md | 163 +++++++++++++++++++++--------------------------- README.md | 2 + 3 files changed, 77 insertions(+), 92 deletions(-) diff --git a/.travis.yml b/.travis.yml index 2c93c74..befeedc 100644 --- a/.travis.yml +++ b/.travis.yml @@ -2,6 +2,10 @@ language: node_js node_js: - "12" - "10" +before_install: + # Create a master branch for commitlint + # https://github.com/conventional-changelog/commitlint/issues/6 + - git remote set-branches origin master && git fetch deploy: on: tags: true diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2c9565e..2635277 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,145 +1,124 @@ -# Contributing +# Contributing to amex-jest-preset -The following guidelines must be followed by all contributors to this repository. Please review them carefully and do not hesitate to ask for help. +✨ Thank you for taking the time to contribute to this project ✨ -### Code of Conduct +## 📖 Table of Contents -* Review and test your code before submitting a pull request. -* Be kind and professional. Avoid assumptions; oversights happen. -* Be clear and concise when documenting code; focus on value. -* Don't commit commented code to the main repo (stash locally, if needed). +* [Code of Conduct](#code-of-conduct) +* [Developing](#developing) +* [Submitting a new feature](#submitting-a-new-feature) +* [Reporting bugs](#reporting-bugs) +* [Contributing](#getting-in-contact) +* [Coding conventions](#coding-conventions) -### Git Commit Guidelines +## Code of Conduct + +This project adheres to the American Express [Code of Conduct](./CODE_OF_CONDUCT.md). By contributing, you are expected to honor these guidelines. -We follow precise rules for git commit message formatting. These rules make it easier to review commit logs and improve contextual understanding of code changes. This also allows us to auto-generate the CHANGELOG from commit messages. +## Developing -Each commit message consists of a **header**, **body** and **footer**. +### Installation -#### Header +1. Fork the repository `amex-jest-preset` to your GitHub account. +2. Afterwards run the following commands in your terminal -The header is required and must not exceed 70 characters to ensure it is well-formatted in common git tools. It has a special format that includes a *type*, *scope* and *subject*: + ```bash + $ git clone https://github.com//amex-jest-preset + $ cd amex-jest-preset + ``` -Syntax: + > replace `your-github-username` with your github username -```bash -(): -``` +3. Install the dependencies by running -#### Type + ```bash + $ npm install + ``` -The *type* should always be lowercase as shown below. +4. You can now run any of these scripts from the root folder. -##### Allowed `` values: +#### Running tests -* **feat** (new feature for the user) -* **fix** (bug fix for the user, not a fix to build scripts) -* **docs** (changes to documentation) -* **style** (formatting, missing semi colons, etc; no functional code change) -* **refactor** (refactoring production code, eg. renaming a variable) -* **test** (adding missing tests, refactoring tests; no production code change) -* **chore** (updating build/env/packages, etc; no production code change) +- **`npm run lint`** -#### Scope +Verifies that your code matches the American Express code style defined in +[`babel-preset-amex`](https://github.com/americanexpress/babel-preset-amex). -The *scope* describes the affected code. The descriptor may be a route, component, feature, utility, etc. It should be one word or camelCased, if needed: -```bash -feat(transactions): added column for quantity -feat(BalanceModule): initial setup -``` +- **`npm test`** -The commit headers above work well if the commit affects many parts of a larger feature. If changes are more specific, it may be too broad. To better clarify specific scopes, you should use a `feature/scope` syntax: +Runs unit tests. -```bash -fix(transaction/details): missing quantity field -``` +- **`npm run test:git-history`** -The above syntax helps reduce verbosity in the _subject_. In comparison, consider the following example: +Verifies the format of all commit messages on the current branch. -```bash -fix(transaction): missing quantity field in txn details -``` +- **`npm posttest`** -Another scenario for scope is using a `route/scope` (or `context/scope`) syntax. This would be useful when a commit only affects a particular instance of code that is used in multiple places. +Verifies the format of all commit messages on the current branch. -*Example*: Transactions may be shown in multiple routes/contexts, but a bug affecting transaction actions may only exist under the "home" route, possibly related to other code. In such cases, you could use the following format: +Runs linting on the current branch and checks that the commits follow [conventional commits](https://www.conventionalcommits.org/) -```bash -fix(home/transactions): txn actions not working -``` +## Submitting a new feature -This header makes it clear that the fix is limited in scope to transactions within the home route/context. +When submitting a new feature request or enhancement of an existing features please review the following: -#### Subject +### Is your feature request related to a problem -Short summary of the commit. Avoid redundancy and simplify wording in ways that do not compromise understanding. +Please provide a clear and concise description of what you want and what your use case is. -Good: +### Provide an example -```bash -$ git commit -m "fix(nav/link): incorrect URL for Travel" -``` +Please include a snippets of the code of the new feature. -Bad: +### Describe the suggested enhancement -```bash -$ git commit -m "fix(nav): incorrect URL for Travel nav item :P" -``` +A clear and concise description of the enhancement to be added include a step-by-step guide if applicable. +Add any other context or screenshots or animated GIFs about the feature request -> Note that the _Bad_ example results in a longer commit header. This is partly attributed to the scope not being more specific and personal expression tacked on the end. +### Describe alternatives you've considered -**Note regarding subjects for bug fixes:** +A clear and concise description of any alternative solutions or features you've considered. -Summarize _what is fixed_, rather than stating that it _is_ fixed. The _type_ ("fix") already specifies the state of the issue. +## Reporting bugs -For example, don't do: +All issues are submitted within GitHub issues. Please check this before submitting a new issue. -```bash -$ git commit -m "fix(nav): corrected Travel URL" -``` +### Describe the bug -Instead, do: +A clear and concise description of what the bug is. -```bash -$ git commit -m "fix(nav): broken URL for Travel" -``` +### Provide step-by-step guide on how to reproduce the bug +Steps to reproduce the behavior, please provide code snippets or a link to repository -#### Body and Footer (optional) +### Expected behavior -The body and footer should wrap at 80 characters. +Please provide a description of the expected behavior -The **body** describes the commit in more detail and should not be more than 1 paragraph (3-5 sentences). Details are important, but too much verbosity can inhibit understanding and productivity -- keep it clear and concise. +### Screenshots -The **footer** should only reference Pull Requests or Issues associated with the commit. +If applicable, add screenshots or animated GIFs to help explain your problem. -For bug fixes that address open issues, the footer should be formatted like so: +### System information -```bash -Closes #17, #26 -``` -and for Pull Requests, use the format: +Provide the system information which is not limited to the below: -```bash -Related #37 -``` +- OS: [e.g. macOS, Windows] +- Browser (if applies) [e.g. chrome, safari] +- Version of amex-jest-preset: [e.g. 5.0.0] +- Node version:[e.g 10.15.1] -If a commit is associated with issues and pull requests, use the following format: +### Security Bugs -```bash -Closes #17, #26 -Related #37 -``` -> Issues should always be referenced before pull requests, as shown above. +Please review our [Security Policy](./SECURITY.md). Please follow the instructions outlined in the policy. -#### Piecing It All Together +## Getting in contact -Below is an example of a full commit message that includes a header, body and footer: +- Join our [Slack channel](https://one-amex.slack.com) request an invite [here](https://join.slack.com/t/one-amex/shared_invite/enQtOTA0MzEzODExODEwLTlmYzI1Y2U2ZDEwNWJjOTAxYTlmZTYzMjUyNzQyZTdmMWIwZGJmZDM2MDZmYzVjMDk5OWU4OGIwNjJjZWRhMjY) -```bash -refactor(nav/item): added prop (isActive) +## Coding conventions -NavItem now supports an "isActive" property. This property is used to control the styling of active navigation links. +### Git Commit Guidelines -Closes #21 -``` \ No newline at end of file +We follow [conventional commits](https://www.conventionalcommits.org/) for git commit message formatting. These rules make it easier to review commit logs and improve contextual understanding of code changes. This also allows us to auto-generate the CHANGELOG from commit messages. diff --git a/README.md b/README.md index 372dbb1..f4f311c 100644 --- a/README.md +++ b/README.md @@ -67,6 +67,8 @@ and to recipients of software distributed by American Express, You reserve all right, title, and interest, if any, in and to Your Contributions. Please [fill out the Agreement](https://cla-assistant.io/americanexpress/). +Please feel free to open pull requests and see [CONTRIBUTING.md](./CONTRIBUTING.md) to learn how to get started contributing. + ## License Any contributions made under this project will be governed by the [Apache License 2.0](./LICENSE.txt).