Skip to content

Latest commit

 

History

History
157 lines (119 loc) · 5.38 KB

CONTRIBUTING.md

File metadata and controls

157 lines (119 loc) · 5.38 KB

Contributing to AgeModelling

This guide shows the guidelines to contribute to this project.

Project Structure

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

Developer Setup

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.

1. Prepare and set up the package

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

2. Clone the git repository

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.

3. Activate the environment

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

Running the tests

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

Commits

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 result
  • DOC: Documentation change
  • ENH: New functionality
  • PERF: Performance improvement
  • REF: Only refactoring -> moving classes, files, splitting functions
  • TST: Adding/improving testing of existing functions
  • STYLE: No logic impact (indentation, comments, variable names)
  • WIP: Work In Progress not ready for merge
  • GIT: Modify some repository settings (gitignore, gitmodules, others)
  • DEL: Deleted files, functions, classes, resources and so on
  • CI: Changes in the the CI/CD Pipelines

Coding Style Guide

We try following the PEP-8 Standard, and we use Flake-8 for linting the code.