Development - Contributing 🐣¶
First, you might want to see the basic ways to help AuthX and get help
If you already cloned the repository and you know that you need to deep dive into the code, here is a guideline to set up your environment:
Virtual environment with
You can create a virtual environment in a directory using Python's
python -m venv env
That will create a directory
./env/ with the python binaries and then you will
be able to install packages for that isolated environment.
Activate the environment¶
Activate the new environment with:
$ source ./env/bin/activate
Or if you use Bash for Windows (e.g. Git Bash):
$ source ./env/Scripts/activate
To check it worked, use:
$ which pip
$ Get-Command pip
If it shows the
pip binary at
env/bin/pip then it worked. 🎉
Every time you install a new package with
pip under that environment,
activate the environment again.
This makes sure that if you use a terminal program installed by that package (like
pre-commit), you use the one from your local environment and not any other that could be installed globally.
After activating the environment as described above, Now lets install all the package that you need to develop Ormdantic:
$ pip install -e .[test,lint,docs] ---> 100%
It will install all the dependencies in your local environment.
The Dependencies file contains all the dependencies that you need to develop AuthX, which are:
- The Base Dependencies - the ones that are needed to run AuthX. See Installation.
For Providing a good and consistent experience, we recommend using pre-commit - a tool that runs a set of checks before you commit your code.
First you need to install the pre-commit tool, which is installed before with the Dev Dependencies.
Now, install the pre-commit hooks in your
This one will provide a linting check before you commit your code.
.pre-commit-config.yaml contains the following configuration with the
pre-commit-hooks- Some out-of-the-box hooks for pre-commit.
isort- A tool to sort imports.
ruff-pre-commit- A tool to check Python code for errors.
black- A tool to format Python code.
pyupgrade- A tool to upgrade Python syntax.
First, make sure you set up your environment as described above, that will install all the requirements.
The documentation uses MkDocs.
All the documentation is in Markdown format in the directory
To Build AuthX Documentation we need the following packages, which are:
mkdocs- The tool that builds the documentation.
mkdocs-material- The theme that AuthX uses.
mkdocs-markdownextradata-plugin- The plugin that allows to add extra data to the documentation.
Help with translations is VERY MUCH appreciated! And it can't be done without the help from the community. 🌎 🚀
Here are the steps to help with translations.
Tips and guideline¶
- Check the currently existing pull requests for your language and add reviews requesting changes or approving them.
add comments with change suggestions to existing pull requests.
Check the docs about adding a pull request review to approve it or request changes.
Check in the issues to see if there's one coordinating translations for your language.
Add a single pull request per page translated. That will make it much easier for others to review it.
For the languages I don't speak, I'll wait for several others to review the translation before merging.
You can also check if there are translations for your language and add a review to them, that will help me know that the translation is correct and I can merge it.
Use the same Python examples and only translate the text in the docs. You don't have to change anything for this to work.
Use the same images, file names, and links. You don't have to change anything for it to work.
To check the 2-letter code for the language you want to translate you can use the table List of ISO 639-1 codes.
all the dependencies that you need to test AuthX, which are:
pytest- The tool that runs the tests.
pytest-asyncio- The plugin that runs the tests in the background.
requests- The library that makes the requests to the AuthX API.
asynctest- The library that makes the tests asynchronous.
Generate a Test Report¶
As we know, the tests are very important to make sure that AuthX works as expected, that why i provide a multi test for and functions to provide a good test.
If you want to generate the test report: