# 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
```sh
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.

```sh
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.

```sh
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:

```sh
hatch shell dev
```

### Activate Production Environment
To enter the (acmc) production environment, use:

```sh
hatch shell
```

### Deactivate Environment
To exit an environment from hatch, use:

```sh
exit
```

### Running Tests
To run tests using `pytest`, use:

```sh
hatch run pytest
```

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

```sh
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. 

```sh
acmc --help
```

### All code checks
The project run all type and formatting checking

```sh
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

```sh
hatch run black --check .
```

To format the coode and modify the files, use

```sh
hatch run format
```

### Type Checking
The project uses `mypy` for type checking:

```sh
hatch run type
```

## Building the Package
To build the package, use:

```sh
hatch build
```

## Releasing the Package

Update the version number in pyproject.toml

Build the package using:

```sh
hatch build
```

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

Check package using:

```sh
twine check dist/acmc-<version>-py3-none-any.whl
```
Upload to pypi using:

```sh
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

```bash
hatch run docs
```

### Publishing to readthedocs

1. Get an account a [readthedocs](https://app.readthedocs.org/dashboard) 

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](https://git.soton.ac.uk/meldb/concepts-processing/-/issues)

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:

   ```sh
   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

   ```sh
   git checkout -b feature-branch
   ```

4. Make changes and commit them:
   ```sh
   git add .
   git commit -m "Description of changes"
   ```
5. Push your branch:
   ```sh
   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](https://git.soton.ac.uk/meldb/concepts-processing)
- [Documentation](https://git.soton.ac.uk/meldb/concepts-processing/docs)
- [Issue Tracker](https://git.soton.ac.uk/meldb/concepts-processing/-/issues)