Skip to content

Latest commit

 

History

History
137 lines (92 loc) · 6.44 KB

CONTRIBUTING.md

File metadata and controls

137 lines (92 loc) · 6.44 KB

Welcome to the Odev contributing guide

Thank you for investing your time in contributing to Odev!

In this guide you will get an overview of the contribution workflow from opening an issue, creating a PR, reviewing, and merging the PR.

Use the table of contents icon ☰ on the top left corner of this document to get to a specific section of this guide quickly.

New contributor guide

To get an overview of the project, read the README. Here are some resources to help you get started with contributions in general and not specific to this project:

Getting started

To navigate our codebase with confidence, see the introduction to working in the Odev repository.

Issues

Create a new issue

If you spot a problem within Odev, search if an issue already exists. If a related issue doesn't exist, you can open a new issue using a relevant issue form.

Solve an issue

Scan through our existing issues to find one that interests you. You can narrow down the search using labels as filters. See Labels for more information. As a general rule, we don’t assign issues to anyone. If you find an issue to work on, you are welcome to open a PR with a fix.

Make changes

Once you are familiar with how we are working in the Odev repository you can clone the Odev repository locally on your machine.

Install or update to Python 3.10 or above.

Install development requirements through pip and enable pre-commit hooks in the repository:

pip install --user -r requirements-dev.txt
pre-commit install

Create a new branch based on the main branch and give it a name that accurately represents the changes you are about to make:

git checkout -b my-new-feature origin/main

Start with your changes!

Test your changes

Happy with your modifications to the odev codebase? Then it's time to test it and make sure everything still works as expected! Run coverage run -m pytest tests in your terminal, if any of the tests fails you will need to correct your code until it passes.

You implemented a brand new feature? Then it's probably good to implement new tests for it! Check what's inside the tests directory for examples.

If you want to check the coverage of your code, you can now run coverage html and open the file ./htmlcov/index.html in your favorite browser.

Commit your update

Commit the changes once you are happy with them. Don't forget to self-review to speed up the review process!

Pull Request

When you're finished with the changes, create a pull request.

  • Fill the "Ready for review" template so that we can review your PR. This template helps reviewers understand your changes as well as the purpose of your pull request.
  • Don't forget to link the PR to an issue if you are solving one.
  • We may ask for changes to be made before a PR can be merged, either using suggested changes or pull request comments. You can apply suggested changes directly through the UI. You can make any other changes in your fork, then commit them to your branch.
  • As you update your PR and apply changes, mark each conversation as resolved.
  • If you run into any merge issues, checkout this git tutorial to help you resolve merge conflicts and other issues.

Your PR is merged!

Congratulations! The Odev team thanks you! 🎉

Understanding the framework

The Odev framework can be intimidating at first sight, however it is designed so as to be easy to use to implement new commands. The code of the framework dives pretty deep in Python's low-level features at times, but as a command or plugin creator you should not worry about it. Unless you are working on the framework itself, the following topics are the ones you should be interested in learning before starting to code.

Commands

Odev is articulated around commands. A command is an action that will be called through the framework after the user inputted its name into the CLI. An example of running a command using Odev could be odev list --all where list is the command that will be ran. Arguments provided after the command itself (in this example --all) will be passed through to the command to direct features and behaviors.

See Commands to see how commands are defined and extended.

Plugins

Odev can be extended with plugins that are loaded from external GitHub repositories, they could be public or private to your organizations and allow to add new features and commands or modify existing ones.

Plugins can be enabled with the predefined command odev plugin --enable <plugin>.

See Plugins to see how plugins can be created.

Check Known Plugins for a non-exhaustive list of existing plugins.

Commons

Odev heavily relies on reusable modules that are defined under the odev/common directory. Those modules can serve various purposes and while most of them will be a collection of helper methods or classes, others structure the framework and provide features that can be used within or outside of commands.

See Common Modules to learn about the main common modules and how to use them efficiently.