Skip to content

Contributing¤

Hello and thank you for considering contributing to Dotify!

Reading and following these guidelines will help us make the contribution process easy and effective for everyone involved.

This project follows the all-contributors specification. You can read more here.

Code of Conduct¤

By participating and contributing to this project, you agree to uphold our Code of Conduct.

Getting Help¤

In case all you need is an answer to a question, please refrain from opening an issue and instead visit the project's discussion page.

Getting Started¤

Contributions are made to this repository via Issues and Pull Requests (PRs). A few general guidelines that cover both:

  • Search for existing Issues and PRs before creating your own.
  • We work hard to make sure issues are handled in a timely manner but, depending on the impact, it could take a while to investigate the root cause. A friendly ping in the comment thread to the submitter or a contributor can help draw attention if your issue is blocking.

Issues¤

Issues should be used to report problems with the library or request a new feature or documentation change. When you create a new Issue, a template will be loaded that will guide you through collecting and providing the required information.

If you find an Issue that addresses the problem you're having, please add your own reproduction information to the existing issue rather than creating a new one. Adding a reaction can also help in indicating to our maintainers that a particular problem is affecting more than just the reporter.

Pull Requests¤

PRs can be a quick way to get your fix or improvement slated for the next release. In general, PRs should:

  • Only fix/add the functionality in question OR address wide-spread whitespace/style issues, not both.
  • Address a single concern in the least number of changed lines as possible.
  • Be accompanied by a complete Pull Request template (loaded automatically when a PR is created).
  • Add unit or integration tests for added or changed functionality.
  • Any code related changes should be accompanied by corresponding changes to the project's documentation.
  • If your pull request introduces a new feature, the corresponding README section must be updated to reflect this. Make sure you also include an example, showcasing this new functionality.
  • Write clear, concise commit message(s) using the Conventional Commits format. Why?
  • This project only accepts pull requests related to open issues. In case there is no relevant open issue, feel free to create one.

For changes that address core functionality or would require breaking changes (e.g. a major release), it's best to open an Issue to discuss your proposal first. This is not required but can save time creating and reviewing changes.

In general, we follow the "fork-and-pull" Git workflow

  1. Fork the repository to your own Github account
  2. Clone the project to your machine
  3. Create a branch locally with a succinct but descriptive name
  4. Commit changes to the branch
  5. Push changes to your fork
  6. Open a PR in our repository and follow the PR template so that we can efficiently review the changes

Setting up a local development environment¤

The following sections assume that you have already locally cloned the repository.

Installing Poetry¤

The Dotify project utilizes the Poetry Python package manager. Having installed Poetry in the global namespace you may now run poetry shell to create a brand new virtual environment and poetry install, in order to install the project's dependencies (development dependencies as well).

Creating & Using Spotify client credentials¤

Start by visiting the Spotify Developer Portal and creating an account. You are also required to create a Spotify client ID, which you will be using during development. You may reed more here.

Installing pre-commit hooks¤

The project utilizes the pre-commit framework. Having created a virtual environment and installed the required dependencies, you may run pre-commit install --install-hooks to install the git hook scripts.

Testing via tox¤

We are using tox to automate testing on multiple environments.

  • You can lint the code by simply running tox -e lint
  • Checking for type errors, using Mypy, can be achieved via tox -e type-check
  • Checking if your changes follow the project's formatting standard can be done via tox -e fmt-check
  • You may run tox -e py38 to run the library's unit tests using Python 3.8 (the py37, py38 and py39 test environments assume, you have installed Python 3.7, 3.8 or 3.9 accordingly)
  • Alternatively, you may simply run tox to execute all of the above

Note that in order to run the test suite, you must export your client credentials beforehand, as such

export SPOTIFY_ID="<SPOTIFY_ID>"
export SPOTIFY_SECRET="<SPOTIFY_SECRET>"

You may also utilize direnv, so that you avoid re-exporting them every time you spawn a new shell instance.

ATTENTION: Even though, using a .envrc file is far more convenient than re-exporting environment variables each and every time you open up a new shell, it is strongly recommended that, you prefer the first approach as you risk compromising your client credentials otherwise.

(Optional) Installing pyenv¤

pyenv is used, in the context of the Dotify project, in order to determine the project's compatibility with various versions of Python. Installing pyenv is not strictly required, but it is strongly recommended.

Having installed pyenv in the global namespace, you may now run the following snippet, in order to install Python 3.7, 3.8 and 3.9, which, at the time of writing this document, are the only Python versions, supported by Dotify.

pyenv install 3.7.10 3.8.9 3.9.4
pyenv local 3.7.10 3.8.9 3.9.4

You will now be able to run tox (an as a result any test environment subset py3[7|8|9]), without any test environment being skipped due to skip_missing_interpreters.

Feel free to read more about using pyenv, in the context of poetry, here.

Performing development operations via poethepoet¤

We are using poethepoet, to perform various development oriented tasks.

Formatting, type-checking, running the test suite, as well as a few other operations, can be performed by running poe <task>. Please run poe --help (or poetry run poe --help), to list all available operations.

Documenting your changes¤

Dotify utilizes MkDocs to build and deploy its documentation to GitHub Pages. The documentation is auto-generated from the python docstrings throughout the source code. As a result, any code related change should be accompanied by a corresponding change to the method's / class's docstring.

Having made your changes, please run poe docs and make sure that no error is being raised on build time. Afterwards, open http://localhost:8000/ in your browser of choice and make sure that the documentation renders correctly.

Writing your commit message¤

The project's version number and Changelog, depend on a consistent commit history. As a result, your commit message's format is extremely important. Before opening a pull request, please make sure that your commits strictly follow the Conventional Commits format].

Creating a pull request¤

Make sure you review our Pull Request Guidelines, before initiating a PR.