Contributing¶

Contributions are welcome, and they are greatly appreciated! Every little helps, and credit will always be given. You can contribute in many ways.

Types of Contributions¶

Report Bugs¶

Report bugs at https://gitlab.com/opencraft/dev/grove/-/issues.

If you are reporting a bug, please use the bug report template, and include:

your operating system name and version
any details about your local setup that might be helpful in troubleshooting
detailed steps to reproduce the bug
infrastructure provider specific details

Fix Bugs¶

Look through the GitLab issues for bugs. Anything tagged with "bug" and/or "help wanted" is open to whoever wants to fix it.

Implement Features¶

Look through the GitLab issues for features. Anything tagged with "enhancement" and/or "help wanted" is open to whoever wants to implement it.

Write Documentation¶

Grove could always use more documentation, whether as part of the docs, in docstrings, comments, and such.

Submit Feedback¶

The best way to send feedback is to file an issue.

If you are proposing a feature:

explain in detail how it would work
keep the scope as narrow as possible, to make it easier to implement
remember that this is a volunteer-driven project, and that contributions are welcome :)

Get Started¶

Ready to contribute?

Fork https://gitlab.com/opencraft/dev/grove repository
Follow https://grove.opencraft.com/getting-started for setting up a cluster for testing. Please note that using cloud infrastructure will incur some costs.

Install prerequisites

# Remember, we use my-repository for the grove-template fork's name
cd my-repository/grove
python -m virtualenv virtualenv
source virtualenv/bin/activate
pip install -r tools-container/requirements.txt
npm install markdownlint-cli
# Install git-cliff for changelog generation
# Instructions: https://github.com/orhun/git-cliff

Create a branch for local development

git checkout -b gitlab-username/bugfix-or-feature-name

When you're done making changes in Grove CLI, check that your changes are formatted, passing linters, and tests are succeeding. We use CI_PROJECT_DIR="$(pwd)/../../../" make test to run the tests as
```
cd tools-container/grove-cli
make format
make lint
# Set my-repository for the CI_PROJECT_DIR variable and run the tests
CI_PROJECT_DIR="$(pwd)/../../../" make test
```
Update documentation as necessary, and check the results. When adding or reorganizing docs, ensure the mkdocs.yml file is updated accordingly.
```
# source the virtualenv if not already sourced
pip install -r requirements.docs.txt
npx markdownlint-cli docs
make serve
```
Commit your changes and push your branch to GitLab. We use conventional commits, and we require every commit to follow this pattern.
```
git add .
git commit -m "action(scope): summary"
git push origin gitlab-username/bugfix-or-feature-name
```
Submit a merge request on GitLab

Merge Request Guidelines¶

Before you submit a merge request, check that it meets these guidelines:

The merge request should include tests if applicable
If tests are applicable, tests should pass for the merge request
If the merge request adds new functionality, or changes existing one, the docs should be updated
After merging a Merge Request, run git cliff > CHANGELOG.md on the main branch and push changes to main using git commit -sm "chore(changelog): update changelog"

Release Guidelines¶

Release guideline is defined by the releases discovery. Ensuring the changelog is maintained properly since the first tag, the commits are validated by commit lint and changelog is generated by git cliff.

Therefore to have proper release notes, follow the steps below:

Double-check past commits that nothing missed
Run git cliff --tag v<x.x.x> --unreleased --prepend CHANGELOG.md and validate changes, where <x.x.x> is the upcoming release version
Validate changes in CHANGELOG.md
Commit the changes using git commit -sm "chore(changelog): update changelog"
Run git tag v<x.x.x> -sm "chore(release): cut release v<x.x.x>", where <x.x.x> is the upcoming release version
Run git push origin main and git push v<x.x.x>, where <x.x.x> is the new release version
Using GitLab Releases, create a new release and form a release notes based on the latest changelog additions
Update the grove-template repository

In case of any questions, check the workflow defined in the discovery.