Skip to content

Latest commit

 

History

History
90 lines (63 loc) · 4.42 KB

CONTRIBUTING.md

File metadata and controls

90 lines (63 loc) · 4.42 KB
Raw

Contributing to Pinnwand

Welcome to the Pinnwand contributing guide! Your interest in improving Pinnwand is greatly appreciated. In this document, you'll find the steps and guidelines that will help you contribute effectively to the project. We aim to maintain a welcoming and collaborative environment, and every contribution counts, no matter how big or small.

Getting the code

In order to be able to contribute, you'll need to have the repository cloned on your local machine.

To do that, you'll need to:

Setting up the environment

This can be done in multiple ways. However, pinnwand used PDM to manage dependencies so we'll explain how to setup your environment with it.

  • Install DPM

    • This is needed in order to add/update/lock dependencies

  • Installing the dependencies This is as simple as running the following command from the project's root directory

        pdm install

    This will create the virtual environment for you automatically. If you want more control on the creation/reuse of virtual environments, please consult the official docs.

Code style

We use black as our code formatter, so the code style is dictated/enforced by it.

To check if there are needed changes to styling, you can run this command

python -m black src/pinnwand

Running tests

To ensure that contributions do not alter expected behavior or break things, the project has 2 main test suites, e2e and integration.

The e2e runs tests on a browser, to ensure that the user interface displays correct content and behaves correctly from a GUI perspective. The integration runs various integration/unit tests to make sure that different parts of the app behave correctly both independently and with others

  • e2e tests are ran using the following command

    pytest --e2e test/e2e --html=test/e2e/report/index.html --self-contained-html

  • integration tests are ran using the following command:

    pytest --cov=pinnwand test/integration

Running the necessary checks automatically

It's good practice to run code style checks, tests, static code analysis, etc. all together. Having to execute these commands each time manually can become tedious, which is why we use the pre-commit package to setup a client-side git hook and run all of these checks automatically.

Setting up the hook is really simple, all you need to do is:

pre-commit install

Note: Make sure you have the optional dev dependencies installed in order to be able to use pre-commit.

Submitting Your Contributions

After the project is set up and you have an issue assigned to you, you can start working on it.

Once you are happy with your changes:

  1. Push your changes to your fork.
  2. Create a Pull Request against the main Pinnwand repository. Provide a clear description of the changes and any related issue numbers.
  3. Participate in the Code Review process. Be open to feedback and ready to make further tweaks if necessary.

Note: All new features/changes should be accompanied with a test that covers them.

Adding New Dependencies

We strive to keep Pinnwand lightweight and simple, therefore, before adding a new dependency, please consider the following:

  • Can the functionality be achieved without an additional dependency?
  • Is the dependency actively maintained and well-regarded in the community?

If a new dependency is justified, discuss it in your pull request or open an issue for discussion. To add it:

pdm add your-dependency
pdm export -o requirements.txt -f requirements