diff --git a/.github/CODE_OF_CONDUCT.md b/.github/CODE_OF_CONDUCT.md index 60ab5c2..7021b3b 100644 --- a/.github/CODE_OF_CONDUCT.md +++ b/.github/CODE_OF_CONDUCT.md @@ -14,21 +14,21 @@ orientation. Examples of behavior that contributes to creating a positive environment include: -* Using welcoming and inclusive language -* Being respectful of differing viewpoints and experiences -* Gracefully accepting constructive criticism -* Focusing on what is best for the community -* Showing empathy towards other community members +- Using welcoming and inclusive language +- Being respectful of differing viewpoints and experiences +- Gracefully accepting constructive criticism +- Focusing on what is best for the community +- Showing empathy towards other community members Examples of unacceptable behavior by participants include: -* The use of sexualized language or imagery and unwelcome sexual attention or +- The use of sexualized language or imagery and unwelcome sexual attention or advances -* Trolling, insulting/derogatory comments, and personal or political attacks -* Public or private harassment -* Publishing others' private information, such as a physical or electronic +- Trolling, insulting/derogatory comments, and personal or political attacks +- Public or private harassment +- Publishing others' private information, such as a physical or electronic address, without explicit permission -* Other conduct which could reasonably be considered inappropriate in a +- Other conduct which could reasonably be considered inappropriate in a professional setting ## Our Responsibilities diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 18ec8e6..358145d 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -76,11 +76,11 @@ ![Issues][icon-issue-image] -* **Collaboration starts with _Issues_. Changes happen through _Pull Requests_.** +- **Collaboration starts with _Issues_. Changes happen through _Pull Requests_.** View `github-resource-converter's` collaboration and contribution flowcharts: - --- + ***
@@ -90,7 +90,7 @@
- --- + ***
@@ -100,9 +100,9 @@
- --- + *** -* ### 1.1. Create Issues for feature requests and defects. +- ### 1.1. Create Issues for feature requests and defects. _Why:_ @@ -113,51 +113,51 @@ Go ahead! Get started now: - * [![Request a feature][issues-new-feat-image]][issues-new-feat-url] + - [![Request a feature][issues-new-feat-image]][issues-new-feat-url] - * [![Report a defect][issues-new-defect-image]][issues-new-defect-url] + - [![Report a defect][issues-new-defect-image]][issues-new-defect-url] - * [Review all open issues][issues-url] + - [Review all open issues][issues-url] -* ### 1.2. Format titles with **`type(scope): subject`**. +- ### 1.2. Format titles with **`type(scope): subject`**. _Why:_ > ⌦`type` categorizes product changes. Valid types are: > - > * `build`: Changes that affect the build system or external dependencies. - > * `ci`: Changes related to continuous integration, delivery, and deployment tasks. - > * `docs`: Documentation changes. - > * `feat`: A new feature. - > * `fix`: Defect (bug) repair. - > * `perf`: Performance enhancements. - > * `refactor`: Source code design improvements that don't affect product behavior. - > * `style`: Changes involving graphics, typography, etc., as well as source code beautification. - > * `test`: Tests added to increase code coverage, or corrected due to errors. - -* ### 1.3. Fill out the issue template. + > - `build`: Changes that affect the build system or external dependencies. + > - `ci`: Changes related to continuous integration, delivery, and deployment tasks. + > - `docs`: Documentation changes. + > - `feat`: A new feature. + > - `fix`: Defect (bug) repair. + > - `perf`: Performance enhancements. + > - `refactor`: Source code design improvements that don't affect product behavior. + > - `style`: Changes involving graphics, typography, etc., as well as source code beautification. + > - `test`: Tests added to increase code coverage, or corrected due to errors. + +- ### 1.3. Fill out the issue template. _Why:_ > ⌦It keeps communication consistent and unambiguous. -* ### 1.4. Label the issue (optional). +- ### 1.4. Label the issue (optional). _Why:_ > ⌦ We use [`git-labelmaker`][gh-git-labelmaker-url] to categorize Issues (and Pull Requests) consistently. There are four label categories: > - > * `type`: the "kind" of product change. - > * `status`: the state of a change. - > * `priority`: the importance and value of a change. + > - `type`: the "kind" of product change. + > - `status`: the state of a change. + > - `priority`: the importance and value of a change. -* ### 1.5. Monitor your issue for questions. +- ### 1.5. Monitor your issue for questions. _Why:_ > ⌦ The team might need more clarification. -* ### 1.6. Your issue will be either accepted for work, or declined. +- ### 1.6. Your issue will be either accepted for work, or declined. _Why:_ @@ -169,20 +169,20 @@ ![Git Logo][icon-git-logo-image] -* ### 2.1. **Rules** +- ### 2.1. **Rules** `github-resource-converter` manages contributions with the [feature-branch-workflow](https://www.atlassian.com/git/tutorials/comparing-workflows#feature-branch-workflow). -* #### 2.1.1. Makes changes in a topic branch. +- #### 2.1.1. Makes changes in a topic branch. _Why:_ > ⌦ Use an isolated topic branch for parallel product development. Topic branches allow you to submit multiple pull requests without confusion. You can iterate without polluting the master branch with potentially unstable, unfinished code. The `github-resource-converter` team uses: > - > * [Feature-branch-workflow](https://www.atlassian.com/git/tutorials/comparing-workflows#feature-branch-workflow) for small-ish codebases, or - > * [Gitflow Workflow](https://www.atlassian.com/git/tutorials/comparing-workflows#gitflow-workflow) for large applications and monoliths + > - [Feature-branch-workflow](https://www.atlassian.com/git/tutorials/comparing-workflows#feature-branch-workflow) for small-ish codebases, or + > - [Gitflow Workflow](https://www.atlassian.com/git/tutorials/comparing-workflows#gitflow-workflow) for large applications and monoliths -* #### 2.1.2. Favor the topic branch naming convention `GH-{ISSUE_NUMBER}-type-scope`. +- #### 2.1.2. Favor the topic branch naming convention `GH-{ISSUE_NUMBER}-type-scope`. _Why:_ @@ -190,25 +190,25 @@ > > **Examples:** > - > * **feat**: a new feature, e.g., `GH-1-feat-cli-add-authz`. - > * **fix**: a defect/bug repair, e.g., `GH-2-fix-api-logging-error`. - > * **build**: changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm), e.g., `GH-8-build-add-markdown-toc`. - > * **chore**: changes that don't modify src or test files, e.g., `GH-10-remove-unused-files`. - > * **ci**: changes to our CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs), e.g., `GH-9-ci-travis-deploy-semantic-release`. - > * **docs**: documentation changes, e.g., `GH-3-docs-readme-revise-api`. - > * **perf**: change that improves performance `GH-6-perf-quicksort`. - > * **refactor**: code changes that improve design, but neither fixes a bug nor adds a feature, e.g., `GH-5-refactor-extract-class`. - > * **revert**: reverts a previous commit, e.g., `GH-11-revert-7f87cc2`. - > * **style**: changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc), e.g., `GH-4-style-lint`. - > * **test**: add missing tests or correct existing tests, e.g., `GH-7-test-complete-coverage`. - -* #### 2.1.3. Branch out from `master`. + > - **feat**: a new feature, e.g., `GH-1-feat-cli-add-authz`. + > - **fix**: a defect/bug repair, e.g., `GH-2-fix-api-logging-error`. + > - **build**: changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm), e.g., `GH-8-build-add-markdown-toc`. + > - **chore**: changes that don't modify src or test files, e.g., `GH-10-remove-unused-files`. + > - **ci**: changes to our CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs), e.g., `GH-9-ci-travis-deploy-semantic-release`. + > - **docs**: documentation changes, e.g., `GH-3-docs-readme-revise-api`. + > - **perf**: change that improves performance `GH-6-perf-quicksort`. + > - **refactor**: code changes that improve design, but neither fixes a bug nor adds a feature, e.g., `GH-5-refactor-extract-class`. + > - **revert**: reverts a previous commit, e.g., `GH-11-revert-7f87cc2`. + > - **style**: changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc), e.g., `GH-4-style-lint`. + > - **test**: add missing tests or correct existing tests, e.g., `GH-7-test-complete-coverage`. + +- #### 2.1.3. Branch out from `master`. _Why:_ > ⌦ `github-resource-converter` follows the feature-branch-workflow. -* #### 2.1.4. **_Never_** push into the `master` branch. **_Always_** submit a Pull Request. +- #### 2.1.4. **_Never_** push into the `master` branch. **_Always_** submit a Pull Request. _Why:_ @@ -216,7 +216,7 @@ > > It also enables easy peer-review of the code and dedicates forum for discussing the proposed feature. -* #### 2.1.5. Submit a Pull Request as soon as possible. +- #### 2.1.5. Submit a Pull Request as soon as possible. _Why:_ @@ -224,19 +224,19 @@ > > Pull Request pushes also trigger automated CI-services, which help you fail fast and assess quality. -* #### 2.1.6. Rebase your local `master` branch before you ask for PR approvals. +- #### 2.1.6. Rebase your local `master` branch before you ask for PR approvals. _Why:_ > ⌦ Rebasing will merge in the requested branch (`master` or `develop`) and apply the commits that you have made locally to the top of the history without creating a merge commit (assuming there were no conflicts). This results in a nice and clean history. -* #### 2.1.7. Resolve rebase conflicts before Pull Request reviews. +- #### 2.1.7. Resolve rebase conflicts before Pull Request reviews. _Why:_ > ⌦ Rebasing will merge in the `master` branch and apply the commits that you have made locally to the top of it. -* #### 2.1.8. Add reviewers and the label `Status: Needs Review` when the topic branch is ready. +- #### 2.1.8. Add reviewers and the label `Status: Needs Review` when the topic branch is ready. _Why:_ @@ -244,26 +244,26 @@ > > Add the label "Status: Review Needed" formally declares the status of your topic branch, and helps teams filter through issues. -* #### 2.1.9. Delete local and remote topic branches after merging. +- #### 2.1.9. Delete local and remote topic branches after merging. _Why:_ > ⌦ Topic branches should only exist while work is in-progress. Merged topic branches clutter up your list of branches with dead branches. Topic branch deletion also insures that you only ever merge back into `master`. -* #### 2.1.10. Protect your `master` branch. +- #### 2.1.10. Protect your `master` branch. _Why:_ > ⌦ Branch protection prevents production-ready branches from incorporating unexpected and irreversible changes. Learn more about > - > * [GitHub protected branches](https://help.github.com/articles/about-protected-branches/) and - > * [Bitbucket protected branches](https://confluence.atlassian.com/bitbucketserver/using-branch-permissions-776639807.html). + > - [GitHub protected branches](https://help.github.com/articles/about-protected-branches/) and + > - [Bitbucket protected branches](https://confluence.atlassian.com/bitbucketserver/using-branch-permissions-776639807.html). -* ### 2.2. **Feature-branch-workflow** +- ### 2.2. **Feature-branch-workflow** We use the [feature-branch-workflow](https://www.atlassian.com/git/tutorials/comparing-workflows#feature-branch-workflow). We _recommend_ [interactive rebasing](https://www.atlassian.com/git/tutorials/merging-vs-rebasing#the-golden-rule-of-rebasing), too, but that's not required. -- #### 2.2.1. Initialize a Git repository in the product directory (_for new repositories only_). +* #### 2.2.1. Initialize a Git repository in the product directory (_for new repositories only_). For subsequent features and changes, this step should be ignored. @@ -272,7 +272,7 @@ git init ``` -- #### 2.2.2. Checkout a new `feat`ure or `fix` branch. +* #### 2.2.2. Checkout a new `feat`ure or `fix` branch. ```sh # For a new feature branch: @@ -282,7 +282,7 @@ git checkout -b GH--fix-scope-of-change ``` -- #### 2.2.3. Make Changes. +* #### 2.2.3. Make Changes. ```sh git add @@ -293,7 +293,7 @@ > ⌦ `git commit -a` will start an editor which lets you separate the subject from the body. Read more about it in _section 1.3_. -- #### 2.2.4. Follow the Conventional Commits Specification for commit messages. +* #### 2.2.4. Follow the Conventional Commits Specification for commit messages. This project enforces [AngularJS Git Commit Guidelines][git-commit-guidelines-url] (which is now an extension of the [Conventional Commits Specfication][conventional-commits-url]) with [`commitplease`][commitplease-url] pre-commit hooks. @@ -301,7 +301,7 @@ > Consistent, legible Git logs not only facilitate communication, but also enable automated `CHANGELOG` generation and semantic versioning with [`standard-version`][standard-version-url]. - * **`build` commit messages** + - **`build` commit messages** Issues related to product builds. @@ -313,7 +313,7 @@