contributing.md

Contributing

This document summaries the development guide for contributing to the ACMC project.

Prerequisites

To install the ACMC package for development, ensure you have Python 3.9 or later installed.

Clone the Repository

git clone https://git.soton.ac.uk/meldb/concepts-processing.git
cd concepts-processing

Set Up a Virtual Environment

It is recommended to use a virtual environment to manage dependencies.

python -m venv venv
source venv/bin/activate  # On Windows use `venv\Scripts\activate`

Install Dependencies

Using hatch, you can install the necessary dependencies easily.

pip install --upgrade pip
pip install hatch

This will create a virtual environment with all required dependencies.

Development Environment

We have two separate environments to ensure that development dependencies (such as testing tools, linters, or other utilities) don't interfere the production environment.

• default environment: includes the core dependencies to run acmc (e.g., requests, etc.).
• dev environment: includes additional tools for testing, code formatting, linting, and other development workflows (e.g., pytest, black, mypy, etc.).

The development toos used include:

• pytest: testing
• mypy: type checking
• black: code formatting

Activate the Development Environment

To enter the (dev) development environment, use:

hatch shell dev

Activate Production Environment

To enter the (acmc) production environment, use:

hatch shell

Deactivate Environment

To exit an environment from hatch, use:

exit

Running Tests

To run tests using pytest, use:

hatch run pytest

To run a specific test and display print outputs -s, use

hatch run pytest -s -v tests/test_acmc.py::<test_function_name>

Running the CLI

The package provides a command-line interface (CLI) entry point.

acmc --help

All code checks

The project run all type and formatting checking

hatch run check

Code Formatting

The project uses black for code formatting. Ensure your code is properly formatted before committing

To check if any of the code needs to be formatted, run black with the --check option

hatch run black --check .

To format the coode and modify the files, use

hatch run format

Type Checking

The project uses mypy for type checking:

hatch run type

Building the Package

To build the package, use:

hatch build

Releasing the Package

Update the version number in pyproject.toml

Build the package using:

hatch build

Creates file acmc-<version>-py3-none-any.whl in the ./dist directory

Check package using:

twine check dist/acmc-<version>-py3-none-any.whl

Upload to pypi using:

twine upload dist/acmc-<version>-py3-none-any.whl --username __token__ --password <your pypi token>

Updating docs

Docs are created using mkdocs and published at readthedocs.org. mkdocs is configured with mkdocs.yaml in the root repo directory. Mkdocs includes the navigation structure of the document linking to general docs and API docs.

Docs are published at readthedocs https://acmc.readthedocs.io/en/latest/. readthedocs is configured with readthedocs.yml in the root repo directory.

General docs

General docs are written in markdown and stored within the docs directory, e.g. the user guide is ./docs/index.md

API docs

API documentation are automatically generated from docstrings using pdoc, through the following command

hatch run docs

Publishing to readthedocs

1. Get an account a readthedocs

2. Ask to become a maintainer of the acmc project

3. Select the acmc project from the dash board

4. Select builds and press the rebuild button

5. Check the documentation at https://acmc.readthedocs.io/en/latest/

GitLab Workflows

Basic

1. Create an new issue in the Issue Tracker

2. Create a new branch for your feature

You can do this from the issue page in GitLab by selecting "Create Branch", then checkout using:

git pull origin
git checkout -b feature-branch origin/feature-branch   

This works if someone has already created the branch and you want to work on it.

You can also create a new branch in your local repo if it does not exist and it will be created when you push

git checkout -b feature-branch

4. Make changes and commit them:

   git add .
   git commit -m "Description of changes"

5. Push your branch:

   git push origin feature-branch

6. Open a merge request in GitLab.

If you make changes, ensure all tests pass and code formatting is correct before submitting a merge request.

Branches

1. Main Branch (main)

• Represents the stable production-ready code.
• Contains only release versions.
• Direct commits are not allowed; changes must go through a pull request (PR) from dev.
• Merges into main require authorization from a repository maintainer or admin.
• Protected branch settings should enforce code reviews and approvals before merging.

2. Development Branch (dev)

• Used for integration and testing.
• All feature branches must be merged here first before reaching main.
• Regularly synced with main to keep it up to date.

3. Feature Branches (feature-xxx)

• Created for each issue or feature.
• Always branch from dev based on an issue.
• Named according to the issue number and short description (e.g., feature-123-user-auth).
• Can be created directly from the issue page in GitLab by selecting "Create Branch".
• Merged into dev through a pull request.

Pull Request Sequence

1. Create a Feature Branch

   • Branch from dev: git checkout -b feature-xxx dev
   • Alternatively, create the branch from the issue itself in GitLab.
   • Implement feature and commit changes following commit message guidelines.

2. Push the Branch

   • git push origin feature-xxx

3. Create a Merge Request (MR) to dev

   • Ensure code review and approvals before merging.
   • Resolve conflicts if any.

4. Merge to dev

   • Squash and merge when approved.
   • Delete feature branch after successful merge.

5. Release to main

   • Create a merge request from dev to main.
   • Perform final testing.
   • Tag the release with versioning (e.g., v1.0.0).
   • Deploy to production after approval.
   • Requires authorization from a repository maintainer or admin before merging.

Commit Message Guidelines

• Use clear and descriptive commit messages.
• Format: <type>(<scope>): <description>
• Example: docs: git workflow documentation (#issue)
• Types: feat, fix, docs, refactor, test, chore.

Additional Guidelines

• Always pull the latest changes before starting a new feature: git pull origin dev
• Write unit tests for new features.
• Keep feature branches short-lived and regularly updated with dev.

Additional Resources

• Repository
• Documentation
• Issue Tracker