Skip to content

Latest commit

 

History

History
225 lines (167 loc) · 6.93 KB

CONTRIBUTING.md

File metadata and controls

225 lines (167 loc) · 6.93 KB

Sources

If you have questions about how to use SocketStream, here are some useful sources:

  1. SocketStream.org
  2. Google Group
  3. GitHub
  4. IRC channel #socketstream
  5. Twitter @socketstream

Submitting issues

To submit an issue please use SocketStream issue tracker.

Contributing to Source Code

We would love for you to contribute to SocketStream to make it even better. To discuss changes please use the SocketStream issue tracker

Installation Dependencies

Before you can contribute to SocketStream, you'll need to install or configure the following dependencies on your machine:

Working with source code

git clone [email protected]:<github username>/socketstream.git
  • Go to project repository
cd socketstream
  • Add the main SocketStream repository as an upstream remote to your repository
 git remote add upstream https://github.com/socketstream/socketstream.git
  • Install npm dependencies
npm install
  • Make some code changes and run the tests to make sure your code passed required tests:
npm test

Submitting Your Changes

  • Create and checkout a new branch off the master branch for your changes:
git checkout -b new-stuff-branch master
  • Make sure your changes passed the tests:
npm test
npm cover-test
  • Commit your changes with a descriptive commit message, please describe what you have done as detailed as possible
git add -A
git commit
  • Push your branch to Github:
git push origin new-stuff-branch

  • Create a pull request

  • Once your patch is reviewed and merged, please delete your branch and pull both yours and master's changes from the main (upstream - SocketStream) repository:

git push origin :new-stuff-branch
git checkout master
git branch -D new-stuff-branch
git pull --ff upstream master

Git Commit Guidelines

These rules are adopted from the AngularJS commit conventions.

Git commit messages will need to be formatted in a certain format. This is so that we can generate a changelog from the git commit messages.

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>

Examples:

feat(http): add `connect.compress()` middleware to the stack

docs(docs): typo fix

feat(websockets): add transport `engineio`

More efficient engine.io replced socket.io

fix(http): use blue ink instead of red ink

BREAKING CHANGE: `http` now uses blue ink instead of red.

To migrate, change your code from the following:

`http.start('blue')`

To:

`http.start('red')`

Any 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

Is recommended to be one of these (only feat and fix show up in the CHANGELOG.md):

  • feat: A new feature
  • fix: A bug fix
  • docs: 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

Scope

The scope could be anything specifying the place of the commit change. For example cli, http, publish, session, websocket, request etc...

Subject

The subject contains a succinct description of the change:

  • use the imperative, present tense: "change" not "changed" nor "changes"
  • don't capitalize first letter
  • no dot (.) at the end

###Body Just as in the subject, use the imperative, present tense: "change" not "changed" nor "changes" 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.

A detailed explanation can be found in this AngularJS commit conventions document.

Documentation generation

We use ngdocs module for generating documentation files.

We have two type of documentation:

  • API - takes from directly from source code from comments to functions and objects defenition
  • Tutorials - markdown files, located within src/docs and have *.ngdoc extension

To build/re-build documentation run:

    grunt build:docs

To run documentation web site locally the way process will watch for changes and re-building docs on the fly run:

    grunt watch:docs

To update local gh-page branch by merging from master run:

    grunt update:docs

Release

This guide is only for developers who perform releases

There are helpful grunt tasks for overall version releasing process:

  1. First of all we need put a mark into GIT History Tree by increasing patch version by 1, adding suffix "SNAPSHOT" (ex. "0.3.15-SNAPSHOT") and commiting package.json:
    grunt release:start

  1. Then we can perform regular commits with changes and pull requests

  2. Once we decide to release a new version we need to prepeare release and run all the tests, generate CHANGELOG.md since the release start point (mark commit from step 1) and clean up version to just "0.3.15":

grunt release:prepare
  1. If previouse step passed we need to complete release by commiting CHANGELOG.md, package.json and adding version tag:
grunt release:complete
  1. Finnaly if all good, just push tags and both master and gh-pages branches to origin:
grunt release:push

You are all set! Thank you for your contribution!