Contributing

Open source software thrives on people’s contributions. We sincerely appreciate your interest in contributing to the MorphoCluster project!

Bug Reports

Bug reports play a vital role! Before submitting a bug report, please take a moment to check the GitHub issues to ensure that the bug hasn’t already been reported.

Code Contributions

Steps for Submitting Code

GitHub Pull Requests are the preferred method for collaborating on code in this project. To contribute, please follow these steps:

Fork the MorphoCluster repository on GitHub and clone your fork locally:
```
git clone ...
```
(Insert the URL of your fork.)
Configure the the “upstream” remote to be able to get the latest changes from the central repository:
```
git remote add upstream https://github.com/morphocluster/morphocluster.git
```
(This only needs to be done once for each local clone.)

Create a new branch for the fix or feature that you’re about to implement:

# Switch to "main" branch
git checkout main

# Pull the latest changes from the central repository
git pull upstream main

# Push the latest changes to your fork (optional)
git push

# Create and checkout a new branch named "fix-xy"
git checkout -b fix-xy

(fix-xy is a placeholder. Chose a speaking name.)

Implement your changes.
Write meaningful commit messages to document your changes.
Push your local changes to your fork on GitHub:
```
git push -u origin fix-xy
```
Submit a GitHub Pull Request. Your contribution will be reviewed promptly.
It might happen that new changes appear on the upstream main branch. These need to be merged into your feature branch:
```
# Pull the latest changes from the central repository
git pull upstream main
```

Used frameworks

MorphoCluster currently uses the following (outdated) versions of certain dependencies:

Flask v1.1 <https://flask.palletsprojects.com/en/1.1.x/> (Not v3!)
Vuetify v2 <https://v2.vuetifyjs.com/en/> (Not v3!)

VS Code Dev Container

The repository contains a VS Code .devcontainer configuration. See the official VS Code documentation: Developing inside a Container.

To build the devcontainer Docker image, BuildKit is required. It is recommended to include the following in your .bashrc:

# Use BuildKit
DOCKER_BUILDKIT=1
COMPOSE_DOCKER_CLI_BUILD=1
BUILDKIT_PROGRESS=plain

Running the services

Both the backend (Flask) and frontend (Vue) frameworks support hot reloading. This means that after saving the code from the editor, the services reload automatically and changes should be visible instantaneously. To enable this behavior, open two terminals, one for the backend, one for the frontend.

Backend:

cd morphocluster/frontend
flask run

# The output looks similar to this:

   * Serving Flask app "morphocluster" (lazy loading)
   * Environment: development
   * Debug mode: on
   * Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)
   * Restarting with stat
   * Debugger is active!
   * Debugger PIN: XXX-XXX-XXX

Frontend:

cd morphocluster/frontend
npm run serve

# The frontend is built in-place.
# After a while, the output looks similar to this:

   DONE  Compiled successfully in 5040ms

   App running at:
   - Local:   http://localhost:8080/frontend/
   - Network: http://172.25.0.2:8080/frontend/

   Note that the development build is not optimized.
   To create a production build, run npm run build.

Then, open the address of the frontend in your browser.

Updating dependencies

Dependencies are declared in environment.base.yaml (general) and environment.dev.yaml (development only). Run gen-conda-lock.sh to regenerate the lock file, then rebuild the devcontainer.

Code Style

To maintain code consistency, please adhere to the following guidelines:

Follow PEP 8, PEP 257, and the Google Style Guide.
Utilize black to format your code.
Use isort to organize your imports.
Employ pydocstyle to receive feedback on your docstrings.

Documentation Contributions

Documentation holds significant value for this library, and we warmly welcome any improvements. The documentation resides in the docs/ directory and is written in reStructuredText. We utilize Sphinx to generate a comprehensive suite of documentation, with napoleon interpreting the docstrings.

To build and preview the documentation, perform the following steps:

cd docs

# Render docs as html
make html

# Start local webserver to display the docs
python -m http.server -d _build/html/