Skip to content

Latest commit

 

History

History
197 lines (128 loc) · 7.36 KB

CONTRIBUTING.md

File metadata and controls

197 lines (128 loc) · 7.36 KB
Raw

Contributing to pystreamapi

We are thrilled to have you here! You, the open source contributors, are what makes this project so great. We appreciate all of your input and contributions to help make pystreamapi the best it can be.

Ways to contribute

There are many ways to contribute to pystreamapi. Here is how you can help:

Important Resources

Reporting Bugs and Feature Requests

We use GitHub issues to track bugs and feature requests. Please ensure your bug description is clear and has sufficient instructions to be able to reproduce the issue. If you are requesting a new feature, please explain why you think it is needed and describe how it should work.

We already created prefilled templates for you to use when creating issues in order to improve the quality of the information you provide.

Please do not use the issue tracker for personal support requests. Instead, use GitHub Discussions.

Branches

The main branch is the stable branch. All development work should be done in a separate branch. When you are ready to submit a pull request, please submit it against the main branch.

The docs branch is the branch used to build the documentation. It automatically updates the GitBook documentation when a pull request is merged into it.

Contributing Code

If you are interested in contributing code to pystreamapi, please follow these steps:

  1. Fork the repository and clone it
  2. Create a new branch for each feature or improvement
  3. Install the development dependencies
  4. Make your changes
  5. Test and lint your code
  6. Commit your changes
  7. Submit a pull request against the main branch
  8. Wait for your pull request to be reviewed and merged

🎉 Congratulations! You have successfully contributed to pystreamapi!

Fork the repository

You can fork the repository by clicking on the "Fork" button in the top right corner of the repository page or by clicking here. This will create a copy of the repository in your own GitHub account.

If you need help with forking a repository, please refer to the GitHub documentation.

After you have forked the repository, you can clone it to your local machine.

Create a new branch

Create a new branch for each feature or improvement you are working on. Please follow our branch naming conventions.

Create the branch from the main branch by running the following command:

git checkout -b BRANCH_NAME main

Install development dependencies

Install Poetry if you haven't already by following the instructions here.

Install the development dependencies by running the following command:

poetry install

Set poetry as the default interpreter for your project in your IDE. This will ensure that the correct dependencies are used when running the project.

Alternatively, you can use the following command to activate the virtual environment:

poetry shell

Make your changes

Make your changes to the code. Please follow the best practices and conventions for python development. You can find them on the official style guide for python code: PEP 8.

Test and lint your code

Testing

Before submitting a pull request, please make sure to write tests and lint the code.

All tests are located in the tests directory. Our tests can be executed using Coverage.py.

To run the tests, execute the following command in the root directory of the project:

coverage run --source "pystreamapi/" -m unittest discover -s tests -t tests --pattern 'test_*.py'

To generate a coverage report, execute the following command and afterwards click on the link to open the report in your browser:

coverage html && cd htmlcov/ && python3 -m http.server

Please make sure that all tests pass and the coverage of your code is 100% before submitting a pull request.

Linting

We use pylint to lint our code. You can run pylint by executing the following command in the root directory of the project after staging your changes:

pylint $(git ls-files '*.py')

Please make sure that your code passes the pylint checks before submitting a pull request.

Commit your changes

We use gitmoji to add emojis to our commit messages. This helps us to quickly identify the purpose of a commit. You can find the list of available emojis and their meaning here.

Please follow this convention when writing commit messages:

:emoji: Short description of the change (less than 50 characters)

Longer (optional) description of the change (wrap at 72 characters)

Please describe your changes in detail in the commit message. This will help us to understand what you have changed and why.

Also, always use the imperative, present tense: "change" not "changed" nor "changes".

Example:

:sparkles: Add data loader for CSV files

Submit a pull request

Push your changes to your forked repository and submit a pull request against the main branch of the original repository.

To push your changes to your forked repository, run the following command:

git push origin BRANCH_NAME

Afterward you can submit a pull request from the GitHub interface.

We require all CI/CD pipelines to pass before merging a pull request. Please make sure that all checks pass and fix failing checks if necessary.

Contributing Documentation

If you are interested in contributing to the documentation, please follow these steps:

  1. Fork the repository and clone it
  2. Create a new branch from the docs branch by running the following command: git checkout -b BRANCH_NAME docs
  3. Add new documentation or update existing documentation
  4. Commit your changes
  5. Submit a pull request against the docs branch

🎉 Congratulations! You have successfully contributed to the documentation of pystreamapi!

Add new documentation or update existing documentation

The documentation is written in Markdown. You can find the documentation in the root of the branch.

You can access the existing documentation here.