Developing, building, and testing readme-inspector
git, node, and npm from a Terminal/CLI (command-line interface).
[![Request a feature][issues-new-feat-image]][issues-new-feat-url] [![Report a defect][issues-new-defect-image]][issues-new-defect-url]
Table of contents
1. Prerequisite software
Before you can build and test readme-inspector, you must install and configure the
following products on your development machine:
Git and/or the GitHub app (for Mac or
Windows ); GitHub’s Guide to Installing
Git is a good source of information.
Node.js , (version specified in the engines field of package.json
NPM (version specified in the engines field of package.json
2. Getting the source code
Fork and clone the readme-inspector repository:
Sign in sign up for a (free) GitHub account .Fork main readme-inspector repository (aka, “origin”).Clone your fork of the readme-inspector repository and define an upstream remote pointing back to the readme-inspector repository that you forked in the first place.
# Clone your GitHub repository:
git clone git@github.com:<github username>/readme-inspector.git
# Go to the readme-inspector directory:
cd readme-inspector
# Add the main readme-inspector repository as an upstream remote to your repository:
git remote add upstream https://github.com/commonality/readme-inspector.git
3. Installing dependencies
Next, install the JavaScript modules needed to build and test readme-inspector:
# Install readme-inspector project dependencies (package.json)
npm install
4. Building
![info][octicon-info] There are currently no build tasks for readme-inspector.
5. Running tests
![check][octicon-check] Your test suites must pass within coverage thresholds before you submit a PR to GitHub.
To run tests:
$ npm test
# => Run all readme-inspector tests on node
$ npm run test :watch
# => Run tests whenever a file changes
Debugging your source code
![bug][octicon-bug] See DEBUG.md for information on debugging the code while running the unit tests.
All tests are executed with Continuous Integration services.
We test on Node.js versions 9, 8, and 7.6.0 on Windows, Mac, and Ubuntu operating systems.
PRs will only be merged once all tests pass.
Travis CI will fail if any of the test suites fails, or a linting rule is violated.
![verified][octicon-verified] readme-inspector uses
ESLint to evaluate and format source code;Fixpack to order all package.json properties consistently; andPrettier to format JSON, Markdown, and YAML.
You can both evaluate and format your all sources by running:
$ npm run lint
# => Formats and lints all JavaScript, JSON, Markdown, and
# package.json.
You can also format sources by type:
# Evaluate and format JavaScript:
npm run lint:js
# Format JSON:
npm run lint:json
# Clean up the product manifest (package.json):
npm run lint:manifest
# Format all markdown files:
npm run lint:md
![alert][octicon-alert] If the source code does not pass linting, the CI will fail and the PR can not be merged.
6. Git rules
![Git Logo][icon-git-logo-image]
readme-inspector manages contributions with the GitHub Flow :
anything in the master branch is always deployable .
6.1. Always create a topic branch or fork from master
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.
6..2. Favor the branch naming convention GH-{ISSUE_NUMBER}-<type>-<scope>[-<subject>]
Why:
⌦ Although not required, our team
Prefixes branches with the GitHub issue number in the format
followed by
The <type> or “kind” of change being introduced, followed by
The <scope> of change, (the feature or module that is changing), followed by
An optional short, descriptive <subject>.
Examples:
feat : a new feature, e.g.,
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, e.g.:
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.:
style : changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc), e.g.:
test : add missing tests or correct existing tests, e.g.:
GH-7-test-complete-coverage
6.3. Never master branch. Always
Why:
⌦ It notifies team members whenever changes occur and allows the community to review your changes at any time.
⌦ It also enables easy peer-review of the code and dedicates forum for discussing the proposed feature.
6.4. Submit a Pull Request as soon as possible
Why:
⌦ Pull Requests declare work in progress. Frequent pushes to a Pull Request notify your team members about change, and gives them the opportunity to provide feedback more often.
⌦ Pull Request pushes also trigger automated CI-services, which help you fail fast and assess quality.
6.5. Add reviewers and the label Status: Needs Review when the topic branch is ready
Why:
⌦ When you add a Reviewer, GitHub (or Bitbucket) notifies teammates that your topic branch meets all Acceptance Criteria and is ready to be merged into master.
Add the label Status: Review Needed and someone in the community will take a look.
6.6. 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.
6.7. Protect the master branch
Why:
⌦ Branch protection prevents production-ready branches from incorporating unexpected and irreversible changes. Learn more about
GitHub protected branches andBitbucket protected branches .
6.8. GitHub workflow
We use the feature-branch-workflow . We recommend interactive rebasing , too, but that’s not required.
6.8.1. Initialize a Git repository in the product directory (for new repositories only ).
For subsequent features and changes, this step should be ignored.
cd <product-repo-directory>
git init
6.8.2. Checkout a new feature or fix branch.
# For a new feature branch:
git checkout -b GH-<issueId>-feat-scope-of-change
# For branches that address defects:
git checkout -b GH-<issueId>-fix-scope-of-change
6.8.3. Make Changes.
Why:
⌦ git commit -a will start an editor which lets you separate the subject from the body. Read more about it in section 1.3 .
6.8.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.
Why:
Consistent, legible Git logs not only facilitate communication, but also enable automated CHANGELOG generation and semantic versioning with [standard-version][standard-version-url] and [semantic-release][semantic-release-url].
Click here for conventional commit definitions with examples.
1. **`BREAKING CHANGES` commit messages**
Commits that change the public API of your product.
> ![info][octicon-info] BREAKING CHANGES result in a MAJOR version bump.
```shell
():
BREAKING CHANGE:
```
1. **`build` commit messages**
Issues related to product builds.
```shell
build():
<[body]>
```
1. **`chore` commit messages**
Issues related to miscellaneous non-functional changes (usually "maintenance" changes).
```shell
chore():
<[body]>
```
1. **`ci` commit messages**
Issues related to continuous integration, delivery, and deployment tasks.
```shell
ci():
<[body]>
```
1. **`docs` commit messages**
Issues related to documentation.
```shell
docs():
<[body]>
```
1. **`feat` (feature) commit messages**
New feature or enhancement requests.
```shell
feat():
<[body]>
```
1. **`fix` commit messages**
Defect (bug) repair issues.
```shell
fix():
<[body]>
```
1. **`perf` (performance) commit messages**
Performance improvement issues.
```shell
perf():
<[body]>
```
1. **`refactor` commit messages**
Source code design **improvements that do not affect product behavior**.
```shell
refactor():
<[body]>
```
1. **`revert` commit messages**
Tasks that revert to a previous commit hash. Your message should begin with `revert:`, followed by the header of the reverted commit.
In the body it should say: `This reverts commit .`, where the hash is the SHA of the commit being reverted.
```shell
revert:
This reverts commit .
```
1. **`style` commit messages**
Issues related to style guideline compliance, especially `ESLint` errors and warnings.
```shell
style():
<[body]>
```
1. **`test` commit messages**
Test coverage tasks.
```shell
test():
<[body]>
```
</details>
---
#### 6.8.5. Sync with remote to get changes you’ve missed.
```shell
git checkout master
git pull
```
_Why:_
> ⌦ This will give you a chance to deal with conflicts on your machine while rebasing(later) rather than creating a Pull Request that contains conflicts.
#### 6.8.6. Update your topic branch with the latest changes from `master` by interactive rebase
```sh
git checkout
git rebase -i --autosquash master
```
_Why:_
> ⌦ You can use `--autosquash` to squash all your commits to a single commit. Nobody wants many commits for a single feature in develop branch.
>
> [Learn more about autosquashing Git commits][autosquashing-git-commits-url].
#### 6.8.7. Resolve conflicts (if any occur), and continue rebase
```sh
git add ...
git rebase --continue
```
[Learn more about resolving conflicts][git-resolve-conflicts-url].
#### 6.8.8. Push your branch with the `-f` flag (if necessary).
Rebase changes history, so you might need to force changes into the `remote` branch with the `-f` flag. If someone else is working on your branch, use the less destructive `--force-with-lease`.
```sh
git push -f
```
_Why:_
> ⌦ When you do a rebase, you are changing the history on your topic branch. As a result, Git will reject normal `git push`. Instead, you'll need to use the -f or --force flag.
>
> [Learn more about `--force-with-lease`][force-with-lease-url].
#### 6.8.9. Submit a Pull Request
Once accepted, the Pull request will be approved, merged, closed, and deleted by an administrator.
#### 6.8.10. Remove your local topic branch if you're done
```sh
git branch -D
```
to remove all branches which are no longer on remote
```sh
git fetch -p && \
for branch in `git branch -vv | grep ': gone]' | awk '{print $1}'`; \
do git branch -D $branch; \
done
```
## 7. **Code standards**
[![JavaScript Style Guide][standard-js-badge-image]][standard-js-url] [![ESLint logo][eslint-logo-image]][eslint-url]
### 7.1. Use the Standard JS Style
`readme-inspector` follows the [Standard JS Style][standard-js-url].
### 7.2. Use ESLint to analyze source code.
_Why:_
> ⌦ [ESLint][eslint-url] evaluates JavaScript code (and `--fix`es what it can) whenever `npm test` runs. You can run ESLint directly with:
```shell
npm run lint:js
```
>
View [`readme-inspector's` ESLint rules][eslint-rules-table-url] and their enforcement.
## 8. **Unit testing**
[![Jest JavaScript Testing][jest-logo-image]][jest-url]
### 8.1. Write Jest tests
_Why:_
> ⌦ Behavior-driven development specifications are executable documentation.
1. **Put test files in the `__tests__` directory.**
1. **Use the `.test.js` suffix for all tests.**
### 8.2. Reach 100% code coverage
_Why:_
> ⌦ Full coverage makes automated dependency drift updates safer, which also allows more people to work on the product at the same time.
1. View a test coverage summary in the Terminal:
```shell
npm test
> jest --config=jest.config.json
PASS **tests**/app.js
readme-inspector:app
✓ creates files (1ms)
Test Suites: 1 passed, 1 total
Tests: 1 passed, 1 total
Snapshots: 0 total
Time: 2.595s
Ran all test suites.
----------|----------|----------|----------|----------|----------------|
File | % Stmts | % Branch | % Funcs | % Lines |Uncovered Lines |
----------|----------|----------|----------|----------|----------------|
All files | 100 | 100 | 100 | 100 | |
index.js | 100 | 100 | 100 | 100 | |
----------|----------|----------|----------|----------|----------------|
```
> ![info][octicon-info] Open `/lib/__tests__/coverage/lcov-report/index.html` in a Web browser to view detailed coverage reports.
## 9. **Directory structure**
This document describes how to set up your development environment to build and test readme-inspector. It also explains the basic mechanics of using