Skip to content

Latest commit

 

History

History
150 lines (110 loc) · 8.27 KB

CONTRIBUTING.md

File metadata and controls

150 lines (110 loc) · 8.27 KB

Contributing to @huddly/sdk-interfaces

✨ Thanks for contributing our open source sdk-interfaces module @huddly/sdk-interfaces! ✨

As a contributor, here are some of the guidelines we would like you to follow:

Also, we strongly recommend that you read How to Contribute to Open Source.

How can I contribute?

You as a user of our sdk-interfaces module are the perfect candidate for contributing on improving our documentation: typo corrections, clarifications, more examples.

Please try to be concise and clear when writing documentation, use links when appropriate and write examples if deemd necessary to help the reader understand better.

Give feedback on issues

Contribute on submitted issues by discussing implementation, architecture, design and/or structure. Give feedback or provide additional information.

Submitting a Pull Request

Good pull requests, no matter if they are patches, improvements, or new features, are a fantastic help. Please make sure your Pull Requests remain focused in scope and don't have unrelated commits.

It is Important to ask first before you decide to go ahead and work on a significant pull request (e.g. implementing new features, refactoring) if you don't want to spend time on implementing something that might end up not being merged into master.

If you are unfamiliar with the procedure of creating a Pull Request, fear not. Here is a great tutorial on how to do just that :)

Here is a summary of the steps to follow:

  1. Set up the workspace
  2. If you cloned a while ago, get the latest changes from upstream and update dependencies:
$ git checkout master
$ git pull upstream master
$ rm -rf node_modules
$ npm install
  1. Create a new topic branch to contain your feature, change, or fix:
$ git checkout -b <topic-branch-name>
  1. Make your code changes, following the Coding rules
  2. Push your topic branch up to your fork:
$ git push origin <topic-branch-name>
  1. Open a Pull Request with a clear title and description.

Tips:

  • For ambitious tasks, open a Pull Request as soon as possible with the [WIP] prefix in the title, in order to get feedback and help from the community.
  • Allow Huddly maintainers to make changes to your Pull Request branch. This way, we can rebase it and make some minor changes if necessary. All changes we make will be done in new commit and we'll ask for your approval before merging them.

Coding rules

Documentation

To ensure consistency and quality, all documentation modifications must:

  • Refer to brand in bold with proper capitalization, i.e. GitHub, @huddly/sdk-interfaces, npm
  • Prefer tables over lists when listing key values, i.e. List of options with their description
  • Use links when you are referring to:
    • a @huddly/sdk-interfaces concept described somewhere else in the documentation, i.e. How to contribute
    • a third-party product/brand/service, i.e. Integrate with GitHub
    • an external concept or feature, i.e. Create a GitHub release
    • a package or module, i.e. The device-api-usb module
  • Use the the single backtick code quoting for:
    • commands inside sentences, i.e. the start detector command
    • programming language keywords, i.e. function, async, String
    • packages or modules, i.e. The @huddly/device-api-usb module
  • Use the the triple backtick code formatting for:
    • code examples
    • configuration examples
    • sequence of command lines

Commit message guidelines

In order to structure a commit in a clean, understandable and parsable way, we use an npm module called commitizen. Using commitizen you will be promted with a wizard that asks you a few meta questions about your commit. Please keep in mind that the commit messages will be included in the release notes, therefore it is important that you use the proper way of creating a git commit message.

Install commitizen on your development environment as a global npm module by running the following command:

npm install -g commitizen

This will create a git alias on your development environment which you can use in the following way:

  • Proceed with your normal development workflow
  • Stage your changes using git add
  • Run git cz to start the interactive commit message CLI

This module has a pre-commit hook that runs prettier-check and build npm scripts before each commit. Make sure that these checks pass before you run git cz as all meta information given on the interactive mode will be discarded if the pre-commit hook fails.

NOTE We require that you have properly formatted commits when submitting a PR.

Tips:

If you are used to creating a lot of commits before submitting a pull request, you can create standard git commits during development. However, when preparing your feature branch for PR and merge, make sure you do the following:

  • Squash all yourt commits in one (if possible)
  • Create a new commit using git cz with a proper commit message
  • Rebase your commits so that all your previously squashed commits are rebased into your last properly formatted commit. Use that commit to submit the PR.

Examples:

Author: Brikend Rama <brikend@huddly.com>
Date:   Wed Jun 5 09:41:05 2019 +0200

feat(release-process): added plugins for aiding release process

Using the commitizen and az-conventional-changelog dependenceis it is possible to structure the
commit message in a proper and standard way which will help possible another module for generating the release notes when releasing a new version of the sdk dependency

Working with the code

Fork the project, clone your fork, configure the remotes and install the dependencies:

# Clone your fork of the repo into the current directory
$ git clone git@github.com:Huddly/sdk-interfaces.git
# Navigate to the newly cloned directory
$ cd sdk-interfaces
# Assign the original repo to a remote called "upstream"
$ git remote add upstream git@github.com:Huddly/sdk-interfaces.git
# Install the dependencies using npm
$ npm install

Lint

The project uses tsling for linting with the Arbinb Linting Standard and Prettier for code formatting.

When running a git commit command, the precommit hook is triggered which will run the linting and code formatting commands respectively. If your code has linting or formatting issues, your commit will be aborted.

You can also run the linter and code foramtter commands manually for fixing the formatting problems on your code changes:

$ npm run tslint
$ npm run prettier

Releasing

To release you need to be a verified contributer.

Run release:major, release:minor or release:patch depending on how big the change is. Followed by npm publish which will publish to the registry. After this is done it is important to update test_version file in the camerasw tests so the new version gets tested with the correct camera sw. Add

sha-to-cli-with-correct-sdk new-sdk-version

for example.

cbaf87ee9c4a8235e29d2f3f5d297fb504bba7a 0.4.X