Skip to content

Latest commit

 

History

History
229 lines (162 loc) · 7.55 KB

CONTRIBUTING.md

File metadata and controls

229 lines (162 loc) · 7.55 KB
Raw

Contributing

Looking to contribute something? Here's how you can help.

Please take a moment to review this document in order to make the contribution process easy and effective for everyone involved.

Following these guidelines helps to communicate that you respect the time of the developers managing and developing this open source project. In return, they should reciprocate that respect in addressing your issue or assessing patches and features.

Code of Conduct

Help us keep this community open and inclusive. Please read and follow our Code of Conduct.

Using the issue tracker

The issue tracker is the preferred channel for bug reports, features requests and submitting pull requests, but please respect the following restrictions:

  • Please do not derail or troll issues. Keep the discussion on topic and respect the opinions of others.

  • Please do not post comments consisting solely of "+1" or ":thumbsup:". Use GitHub's "reactions" feature instead. We reserve the right to delete comments which violate this rule.

Bug reports

A bug is a demonstrable problem that is caused by the code in the repository. Good bug reports are extremely helpful, so thanks!

Guidelines for bug reports:

  1. Validate you code to ensure your problem isn't caused by a simple error in your own code.

  2. Use the GitHub issue search — check if the issue has already been reported.

  3. Check if the issue has been fixed — try to reproduce it using the latest master or development branch in the repository.

  4. Isolate the problem — ideally create a reduced test case to demonstrate the bug.

Feature requests

Feature requests are welcome. But take a moment to find out whether your idea fits with the scope and aims of the project. It's up to you to make a strong case to convince the project's developers of the merits of this feature. Please provide as much detail and context as possible. Our time is limited but we are open for pull requests.

Pull requests

Good pull requests—patches, improvements, new features—are a fantastic help. They should remain focused in scope and avoid containing unrelated commits.

Please ask first before embarking on any significant pull request (e.g. implementing features, refactoring code), otherwise you risk spending a lot of time working on something that the project's developers might not want to merge into the project.

Please adhere to the coding rules used throughout the project (indentation, accurate comments, etc.) and any other requirements (such as test coverage).

Adhering to the following process is the best way to get your work included in the project:

  1. Fork the project, clone your fork, and configure the remotes:

    # Clone your fork of the repo into the current directory
git clone https://github.com/<your-username>/<project>.git
# Navigate to the newly cloned directory
cd <project>
# Assign the original repo to a remote called "upstream"
git remote add upstream https://github.com/xtreamwayz/<project>.git

  2. Get the latest changes from upstream:

    git checkout master -f
git pull --ff upstream master
# And optionally, to update your fork
git push origin master:master

  3. Create a new topic branch (off the main project development branch) to contain your feature, change, or fix:

    git checkout -b <patch-branch-name>

  4. Commit your changes in logical chunks. Please adhere to the conventional commits specification or your code is unlikely be merged into the main project. Use Git's interactive rebase feature to tidy up your commits before making them public.

    git commit -a

  5. Push your branch up to your fork:

    git push origin <patch-branch-name>

  6. Open a Pull Request with a clear title and description against the master branch.

  7. If changes are suggested then:

    • Make the required updates.
    • Re-run the test suites 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

That's it!

After your pull request is merged

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

    git push origin --delete <patch-branch-name>

  • Check out the master branch:

    git checkout master -f

  • Delete the local branch:

    git branch -D <patch-branch-name>

  • Update your master with the latest upstream version:

    git pull --ff upstream master

IMPORTANT: By submitting a patch, you agree to allow the project owners to license your work under the terms of the MIT License (if it includes code changes) and under the terms of the Attribution 4.0 International License (CC BY 4.0) (if it includes documentation changes).

Coding Rules

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

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>[optional scope]: <description>

[optional body]

[optional footer(s)]

The header is mandatory and the scope of the header is optional.

The footer should contain a closing reference to an issue if any.

Samples: (even more samples)

docs(changelog): update changelog to 1.0.0-alpha.1

fix: need to depend on latest rxjs and zone.js

The version in our package.json gets copied to the one we publish, and users
need the latest of these.

closes #1

Revert

If the commit reverts a previous commit, it should begin with revert: , followed by the header of the reverted commit. In the body it should say: This reverts commit <hash>., where the hash is the SHA of the commit being reverted.

Type

Must be one of the following:

  • build: Changes that affect the build system or external dependencies (example scopes: composer, npm)
  • ci: Changes to our CI configuration files and scripts (example scopes: GitHub Actions, Circle, Travis)
  • docs: Documentation only changes
  • feat: A new feature
  • fix: A bug fix
  • perf: A code change that improves performance
  • refactor: A code change that neither fixes a bug nor adds a feature
  • style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
  • test: Adding missing tests or correcting existing tests