Skip to content

Latest commit

 

History

History
155 lines (83 loc) · 7.3 KB

CONTRIBUTING.md

File metadata and controls

155 lines (83 loc) · 7.3 KB
Raw

Contributing

We love contributions from everyone. By participating in this project, you agree to abide by the code of conduct adopted by xFAANG.

We expect everyone to follow the code of conduct anywhere in xFAANG's project codebases, issue trackers, pull request comments, chatrooms, and mailing lists.

Contributing Code - Quick Start

  1. Choose a good issue to work on.

  2. For bigger issues, discuss your solution with the community.

  3. Fork the repo.

  4. Make your change, write tests.

    1. Please write tests for your changes in behaviour in AskQL modules.
    2. Format code with Prettier.
    3. For commit message use Conventional Commits format with more commit types (see this Gist).

  5. Push and create a PR

    1. For the PR message also use Conventional Commits format with more commit types (see this Gist).
    2. Mention which issue the PR is closing or fixing, e.g. 'Closes #10' (more info here)

Technical note: We squash-merge PRs.

Contributing Code - Details

Choose a good issue to work on

You can find all the issues here:

https://github.com/xFAANG/askql/issues

If you have noticed a new bug or have your own idea on an enhancement, feel free to submit it there.

New contributors

If you are a new contributor:

  1. Filter issues by a label 'good first issue'.

    This way you will see tasks that others thought are a good start. Don't be surprised that some of them relate to the parts of code you don't understand or wouldn't like to touch at all. This is completely normal. Just find a single issue you would like to work on and commit to it.

  2. If you know how to tackle your chosen issue, that's great, work on it and create a commit and a PR with your change.

  3. If you don't know how to start, it most probably means we should have written more pointers :) In such case, we need your help - your feedback!

  4. Remember good practices with global gitignore file configuration. If you don't know how to configure global gitignore see this Gist. We recommend to exclude your local configuration files for your system and code editor.

    So be brave and reach out to us, either by tagging one of the Core Developers by their username in your chosen issue or by writing on the Discord community.

    We will be very very happy to help you start, and your feedback will improve the pointers for the future new contributors and make their start smoother.

If needed, discuss your solution with the community

For small issues you can just start your contribution straightaway.

The bigger the issue is, the more discussion might be needed. Please write on the page with your issue or, if more real-time conversation is needed, write on our Discord community and write just the summary on the issue page.

Fork the repo.

  1. Fork the repo.

  2. Clone the repo:

     git clone https://{yourGithubUsername}@github.com/{yourGithubUsername}/askql.git

    Don't forget to replace {yourGithubUsername} with your github username.

  3. Install dependencies:

    npm i

  4. Build the project:

    npm run build

  5. Make sure the tests pass (and if they didn't, please submit an issue on Github :) )

    npm test

Make your change, write tests

This is one of the most time-consuming tasks in the process :)

  1. Make sure your code works well and looks well too. Code is written once but read multiple times.

  2. If your change alters the behavior of AskQL components, please please create tests for your change in one of the __tests__ directories. Choose the directory or directories which reflect the best the nature of the change.

    In case of any doubts on tests, write on the Github page with your issue or on our Discord community.

  3. Make sure all tests pass:

    npm test

  4. Make sure code conforms to the Prettier plugin settings in the project. Best, use a Prettier extension to your IDE to auto-format the code (e.g. for VS Code use Prettier - Code formatter).

  5. Write a good commit message. We use Conventional Commits format with more commit types (see this Gist).

New contributor - Before you commit

There are a few things to check before you commit:

  1. Did you format your code correctly?

    We are using Prettier to check code style. When you commit, git will validate whether your changes keep the style. Please reformat the code using Prettier before committing (when using VS Code we suggest installing Prettier - Code formatter extension and turning on autoformatting before save).

  2. Did you write tests for your change?

    We advise to try to write tests for every change of behavior in AskQL components.

  3. Did you run all the tests?

    Run npm test to check if all tests pass. Note that while your own tests may pass, your change might be breaking existing tests.

Push and create a PR

  1. Push to your fork.

  2. Submit a pull request.

    When naming your pull request, please use the same format as for the commits: Conventional Commits with more commit types (see this Gist).

    Mention which issue the PR is closing or fixing, e.g. 'Closes #10' (more info here).

  3. Others will give constructive feedback.

    This is a time for discussion and improvements. At this point you might need to make some necessary changes before your contribution gets approved. Generally, the better discussion you make before working on a (big) issue, the shorter this step should take.

  4. After your pull request is approved, either it will be merged by the approver or you will merge it.

    A technical note: Currently all commits in PR are squashed on merge (no action needed here).

Other notes

The versioning scheme we use is SemVer.

License

Any contributions you make will be under the MIT Software License. In short, when you submit code changes, your submissions are understood to be under the same MIT License that covers the project. Feel free to contact the maintainers if that's a concern.

New bugs and enhancements

You are always welcome to open an issue on AskQL Github issues.

Getting Help

If you need anything, write on our Discord community.

References

This document was based on Thoughtbot templates https://github.com/thoughtbot/templates