Skip to content

Latest commit

 

History

History
153 lines (111 loc) · 6.95 KB

CONTRIBUTING.md

File metadata and controls

153 lines (111 loc) · 6.95 KB

Contributing

Build Status

I'm glad you find Jowl useful enough that you want to help out! Thank you!

Please note that I get time to work on Jowl in fits and bursts, so issues and pull requests may sit for up to a month before I have a chance to initially respond to them. Please don't be discouraged if it takes a little while.

Issues

Please file an issue for any of the following reasons:

  • You've encountered a bug
  • You found behavior that surprised you (ease-of-use is an explicit Jowl design goal)
  • You have an idea for new feature that would fit well into Jowl
  • To tell me how you're using Jowl (understanding people's use-cases helps me to improve Jowl)
  • Just to say thanks

If applicable, please include your OS and version of Node.

Pull Requests

I welcome pull requests for bugfixes or features! Consider filing an issue for your feature before spending a lot of time on it to ensure it fits in with Jowl's design philosophy.

Contributions should be licensed under the same license as Jowl.

Don't worry about modifying the changelog or incrementing the package version, I will do that upon release.

See Developing Jowl for detailed instructions.

Developing Jowl

First, ensure the following dependencies are installed:

  1. Fork the Jowl repository and create a local clone of your fork.

  2. Create a topic branch for the feature or bugfix you'd like to work on.

    git checkout master
git checkout -b fix/terrible-bug

  3. Install dependencies

    yarn

  4. Run a build

    yarn run build

    This will run tests, linters, and style checkers for code and documentation.

    Note that build output may be a little difficult to read as lines from different tests are interleaved. Sorry about that.

    If the build doesn't pass, but Continuous Integration shows the same commit passing, there's either something wrong with your development environment, or your platform is different than the ones Jowl is tested on. Feel free to file an issue (and link to the Continuous Integration build for the commit) and we'll get to the bottom of it.

  5. Ensure your text editor is using LF (Unix) line endings.

  6. Write a test for your new behavior and verify that it fails.

  7. Modify the source code or until the build passes again.

    Please conform to the coding standards, which are enforced at build time.

  8. Commit your change. Please conform to the commit standards.

  9. Repeat the previous three steps until your feature or bugfix is complete.

  10. If you've added a feature, please write documentation for it in the Reference and add that as one last commit (alternatively, it's OK to add docs in the same commit where you change functionality).

  11. Push your topic branch to your fork

    git push -u origin fix/terrible-bug

  12. Use the GitHub interface to Create a Pull Request.

  13. CircleCI will begin building your changes and will report their status back to the Pull Request.

Testing

Tests can be run with yarn test.

Every intended behavior in Jowl is tested either with a unit test of the function implementing the behavior or an integration test of the entire program. Prefer unit tests, but if integration tests are useful for externally-facing behavior such as output or options parsing, There is no need to write both unit and integration tests for the same behavior.

Each it() block should work in isolation without depending on other it() blocks having executed.

Jowl's tests use Mocha with Chai expect() matchers.

Standards

Compatability

Jowl is compatible will all current Node LTS versions on both Unix and Windows.

Additionally, several previously-supported Node versions that have been end-of-lifed are supported on a best-effort basis. New changes should make reasonable efforts not to break compatability with end-of-lifed node vesions, but if this becomes too difficult, we'll drop them.

Coding Standards

Jowl is written in ES6.

Source code conforms to the Airbnb Style Guide with a few exceptions. This is checked automatically at build time.

Markdown conforms to Markdownlint rules except for MD013 Line Length. Please write one sentence per line instead, for more useful git diffs. Rules are checked automatically at build time.

All text files use LF (Unix) line endings. This is done because the Airbnb eslint style rules expect LF line endings on disk, and because bin scripts should use LF when being published to NPM. Git is configured convert other line endings to LF on commit so that they are represented as LF in the object database and to check out files as LF in the working directory. A .editorconfig is provided to automatically set line endings in many editors.

Commit Standards

feat(run): add chain runner

Add command runner which works in chain mode. This library will
be used by the executable, which will handle command line
processing and JSON parsing and serialization.

In chain mode, the command is prefixed with a Lodash chain with
the data as the context. After the command, .value() is
automatically called.

Please follow The Seven Rules of a Great Commit Message except for #3 (please don't capitalize the first word).

Commit also messages conform to the Angular Git Commit Guidelines except that the scope in the parentheses should be one of the following:

  • General
    • run
    • cli
    • lint
    • format
  • docs type only
    • readme
    • reference
    • help (text output by running jowl --help)
  • chore type only
    • ci (continuous integration configuration)
    • release
    • deps
  • test type only
    • integration

Note that unlike Angular, the changelogs are not generated automatically from commit messages. I do not believe a one-to-one correspondance between commit messages and changelog lines is useful. Further, the audience for commit messages is other developers, while the audience for changelogs is users.