Skip to content

Development Protocol

Jump to bottom
vegar ringdal edited this page Jun 9, 2016 · 1 revision

(shamelessly copied from https://github.com/aurelia-ui-toolkits/aurelia-kendoui-plugin/wiki/Development-Protocol)

Coding Rules

To ensure consistency throughout the source code, keep these rules in mind as you are working:

  • All features or bug fixes must be tested by one or more specs.
  • All public API methods must be documented. To see how we document our APIs, please check out the existing docs.
  • Instead of complex inheritance hierarchies, we prefer simple objects.

Git Commit Guidelines

We have very precise rules over how our git commit messages can be formatted. This leads to more readable messages that are easy to follow when looking through the project history. But also, we use the git commit messages to generate the change log.

Commit Message Format

Each commit message consists of a header, a body and a footer. The header has a special format that includes a type, a scope and a subject:

<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

The subject line of the commit message cannot be longer 100 characters. This allows the message to be easier to read on GitHub as well as in various git tools.

Type

Please use one of the following:

  • feat: A new feature
  • fix: A bug fix
  • doc: Documentation only changes
  • style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
  • refactor: A code change that neither fixes a bug or adds a feature
  • perf: A code change that improves performance
  • test: Adding missing tests
  • chore: Changes to the build process or auxiliary tools and libraries such as documentation generation

Sample App: use: chore(sample)

(JeroenVinke via Gitter) we should not use refactor/fix/feat in commit messages for the sample app as these show up in the generated CHANGELOG.md file. Just use chore(sample):. Only commit messages for changes to the plugin should contain refactor/fix/feat etc.

Scope

The scope could be anything specifying the location of the commit change. In general, for the aurelia-kendoui project, scopes will apply to either a) a specific Kendo component b) the skeleton or c) all. Examples may be as follows:

chore(autocomplete): add remote support

chore(skeleton): add autocomplete remote sample to demo page

chore(all): add aurelia-datasource support

Commits that update only the demonstration pages should fall under 'skeleton'. This should assist in separating progress on Kendo components vs demo pages.

Subject

The subject contains a succinct description of the change:

  • Use the imperative, present tense: "change" not "changed" nor "changes".
  • Don't capitalize the first letter.
  • Do not add a dot (.) at the end.

Body

The body should include the motivation for the change and contrast this with previous behavior.

Footer

The footer should contain any information about Breaking Changes and is also the place to reference GitHub issues that this commit Closes.

Submitting a Pull Request

Before you submit your pull request consider the following guidelines:

  • Search the appropriate GitHub Repository for an open or closed Pull Request that relates to your submission. You don't want to duplicate effort.

  • Make your changes in a new git branch:

     git checkout -b my-fix-branch master

  • Create your patch, including appropriate test cases.

  • Follow our Coding Rules.

  • Run the full test suite and ensure that all tests pass.

  • Commit your changes using a descriptive commit message that follows our commit message conventions. Adherence to the commit message conventions is required because release notes are automatically generated from these messages.

     git commit -a

    Note: The optional commit -a command line option will automatically "add" and "rm" edited files.

  • Build your changes locally to ensure all the tests pass

     karma start

  • Push your branch to GitHub:

    git push origin my-fix-branch

  • In GitHub, send a Pull Request to the master branch.

  • If we suggest changes then:

    • Make the required updates.
    • Re-run the test suite to ensure tests are still passing.
    • Rebase your branch and force push to your GitHub Repository (this will update your Pull Request):
    git rebase master -i
git push -f

After Your Pull Request is Merged

After your pull request is merged, you can safely delete your branch and pull the changes from the main (upstream) repository:

  • Delete the remote branch on GitHub either through the GitHub web UI or your local shell as follows:

    git push origin --delete my-fix-branch

  • Check out the master branch:

    git checkout master -f

  • Delete the local branch:

    git branch -D my-fix-branch

  • Update your master with the latest upstream version:

    git pull --ff upstream master
Clone this wiki locally