Merge branch '7-document-the-development-environment' into 'dev'

Resolve "Document the development environment"

Closes #7

See merge request meldb/concepts-processing!2

.gitignore

@@ -13,7 +13,7 @@ __pycache__
 ~$*
 
 # Build
-.tox/
+venv/*
 
 # ACMC phenotype build files
 

docs/index.md

@@ -172,10 +172,142 @@ The `phen` command is used phenotype-related operations.
 
   - `-d`, `--phen-dir`: (Optional) Directory of current phenotype configuration (the default is ./build/phen).
   - `-old`, `--phen-dir-old`: (Required) Directory of old phenotype version)
- 
-# GitLab Workflow for Managing Releases
 
-## Branching Strategy
+# Development Guide
+
+## 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.).
+
+### 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 exist an environment from hatch, use:
+
+```sh
+exit
+```
+
+### 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 acmc
+```
+
+To format the coode and modify the files, use
+
+```sh
+hatch run black acmc
+```
+
+### Type Checking
+The project uses `mypy` for type checking:
+
+```sh
+hatch run mypy -p acmc
+```
+
+### Running Tests
+To run tests using `pytest`, use:
+
+```sh
+hatch run pytest
+```
+
+## Building the Package
+To build the package, use:
+
+```sh
+hatch build
+```
+
+## Running the CLI
+The package provides a command-line interface (CLI) entry point. 
+
+```sh
+acmc --help
+```
+
+## Contributing
+
+### GitLab Basic Workflow Overview 
+
+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 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.
+
+## GitLab Workflow for Managing Releases
 
 ### 1. Main Branch (`main`)
 - Represents the stable production-ready code.
@@ -221,14 +353,18 @@ The `phen` command is used phenotype-related operations.
    - Deploy to production after approval.
    - Requires authorization from a repository maintainer or admin before merging.
 
-## Commit Message Guidelines
+### Commit Message Guidelines
 - Use clear and descriptive commit messages.
 - Format: `<type>(<scope>): <description>`
-- Example: `docs (documentation): git workflow documentation (#issue)`
-- Types: `feat` (feature), `fix` (bug fix), `docs` (documentation), `refactor` (code refactoring), `test` (tests), `chore` (maintenance).
+- 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)
\ No newline at end of file

pyproject.toml

@@ -47,23 +47,26 @@ Repository = "https://git.soton.ac.uk/meldb/concepts-processing"
 Documentation = "https://git.soton.ac.uk/meldb/concepts-processing/docs"
 Issues = "https://git.soton.ac.uk/meldb/concepts-processing/-/issues"
 
-[tool.hatch.build]
-include = ["acmc/**"]  # Ensure only the acmc package is included
-
-[tool.hatch.build.targets.sdist]
-include = [
-    "acmc/**",
-]
-
 [tool.hatch.build.targets.wheel]
 packages = ["acmc"]
 
 [tool.hatch.envs.default]
 dependencies = [
     "hatch",
-	"pytest"
+	"pytest",
  ]
 
-[tool.hatch.envs.default.scripts]
-dev = "python -m acmc"
-test = "pytest tests"
+[tool.hatch.envs.dev]
+dependencies = [
+    "pytest",
\ No newline at end of file
+    "black",
+    "mypy"
+]
+
+[tool.hatch.build]
+include = ["acmc/**"]  # Ensure only the acmc package is included
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "acmc/**",
+]
\ No newline at end of file