This guide shows the guidelines to contribute to this project.
The project structure is composed by files which are tracked or ignored by git. Usually only code-related files are tracked, while big files, such as images or binaries, should be avoided.
ageml
│
├── bin # Scripts, CLIs and GUIs that use the package. Not packaged. Helpful for debugging.
│ ├── scripts/
│ ├── main.py # Usually, main entry point for the main application.
│ └── all_that_should_not_be_in_the_build
│
│
│
├── data # NOT TRACKED BY GIT. Where test data should be included in the developers' file systems
│ └──.gitkeep
│
├── docs
│ ├──CONTRIBUTING.md # Contribution Guidelines.
│ └──...
│
├── resources # Folder with figures and other supporting files
│
│
├── src # Contains all the source code of the package
│ └── ageml
│ ├── ...
│ ├── my_awesome_subpkg1
│ │ ├── __init__.py
│ │ └── awesome_fun.py
│ └── my_awesome_subpkg2
│ ├── __init__.py
│ └── awesome_fun.py
│
│
├── tests # Testing folder, follows the package structure of src/pyTemplate
│ ├── __init__.py
│ ├── test_my_awesome_subpkg1
│ └── test_my_awesome_subpkg2
│ ├── __init__.py
│ └── test_awesome_fun
│
│
├── .coverage # File to measure code coverage, percentage of tested code lines
├── README.md
├── pyproject.toml # Requirements for environment settings, packaging and so on
├── poetry.lock # Dependency for building the system
├── noxfile.py # Defines the linting, coverage, pytest sessions
├── setup.cfg # Defines the linting rules
├── LICENSE # Apache 2.0 License file
├── NOTICE # Notice file required by the Apache 2.0 License
└── .gitignore # Files/directories that should not be tracked
This section explains how to set up a local development environment for contributing to the project.
Another section will be added in the future explaining how to setup a Docker container for development.
Poetry is our environment manager and build system. To install the required packages for creating the environment with poetry.
Note: If you are using Mac OS, make sure you are installing pip
correctly, either by installing python3 via homebrew, or other tested methods.
pip install poetry nox nox-poetry
If you want the virtual environment of the project to be located in the project root, run this line (make sure you have poetry installed running poetry --version
):
poetry config virtualenvs.in-project true
Run in your terminal:
git clone https://github.com/compneurobilbao/ageml.git && cd ageml
Once inside the cloned folder (where the pyproject.toml file is located), Poetry will install in the virtual environment (in developer mode) when running:
poetry install
Refer to the poetry documentation for more information.
At this point, a virtual environment should have been created automatically with all the required dependencies. If this is something that could be launched somehow, activate the poetry shell:
poetry shell
Or you can also run:
. <path_to_your_virtual_env>/bin/activate
Before pushing anything with significant changes in code/functionality, tests should be (ideally) run locally. This can be done using pre-commit hooks, or manually. To run the tests manually, first activate the environment, and then run:
nox -s test
For linting:
nox -s lint
For coverage:
nox -s coverage
We try to follow the seven rules of a great Git commit message.
We like using the following standard prefixes for commit messages. Rigidness is not of our liking, so as long as the commit message is informative about its changes, you are good to go.
BUG:
Fix for runtime crash or incorrect resultDOC:
Documentation changeENH:
New functionalityPERF:
Performance improvementREF:
Only refactoring -> moving classes, files, splitting functionsTST:
Adding/improving testing of existing functionsSTYLE:
No logic impact (indentation, comments, variable names)WIP:
Work In Progress not ready for mergeGIT:
Modify some repository settings (gitignore, gitmodules, others)DEL:
Deleted files, functions, classes, resources and so onCI:
Changes in the the CI/CD Pipelines
We try following the PEP-8 Standard, and we use Flake-8 for linting the code.