Skip to content

Files

Latest commit

caffeine-addicttcaffeine-addictt
docs: Add cleanup docs to CONTRIBUTING
Jul 23, 2024
478191a · Jul 23, 2024

History

History
220 lines (165 loc) · 6.07 KB

CONTRIBUTING.md

File metadata and controls

220 lines (165 loc) · 6.07 KB

Contributing

When contributing to this repository, please first discuss the change you wish to make via issue, email, or any other method with the owners of this repository before making a change.

Please note we have a code of conduct; please follow it in all your interactions with the project.

Table of Contents

Setting up the project locally

1. Pre-requisites

Nexis uses GNU/Make to automate many of the processes like building, testing and linting. You can check if you have it installed by running make --version.

Nexis uses Poetry to manage CLI dependencies. You can check if you have it installed by running poetry --version.

Nexis uses Go mod to manage Go dependencies. It comes installed with Go. You can check if you have it installed by running go version.

Nexis uses NPM to manage JavaScript dependencies, which are primarily used for code quality and linting. You can check if you have it installed by running npm -v.

Nexis uses Docker and Docker Compose to create and manage containers. You can check if you have it installed by running docker --version and docker compose version.

2. Python Venv

Before running make install, GNU/make assumes that you already have created and activated a Python virtual environment. If you have not, you can do so by running:

# GNU/Linux or MacOs
python3 -m venv venv
source venv/bin/activate

# Windows
py -m venv venv
venv\Scripts\activate.bat

3. Dependencies

You can install the dependencies by running:

make install

You can add Python dependencies by running:

poetry add <name>

You can add Golang dependencies by running:

go get <name>

4. Running Nexis

You can start the server by running:

# RECOMMENDED
# Using docker-compose watch for auto-reloading
# and automatically restarting containers.
#
# Only exposes to localhost port 3000.
make server

# NOT RECOMMENDED
# Using air for hot-reloading and auto-restarting.
# Port is also configurable.
#
# However, this might break on non-linux systems and
# you may encounter "but it works on my system though?" errors.
#
# We will not entertain bug reports for this as this is purely
# for legacy purposes.
make server/go-air

You can run the CLI by running:

poetry install
poetry run nexis

5. Cleanup

You can use make tidy and/or make clean to cleanup your environment.

Tidy

Tidy only removes binaries and caches. It is a less aggressive and preferred version of make clean.

make tidy

Clean

Clean does what tidy does and also deletes node_modules/ and venv/. Thus it is more aggressive and destructive, and may leave your environment in a bad state.

make clean

Pull Request Process

  1. Ensure any install or build dependencies are removed before the end of the layer when doing a build.
  2. Ensure that tests and linting pass.
  3. Update the README.md with details of changes to the interface; this includes new environment variables, exposed ports, valid file locations and container parameters.
  4. Increase the version numbers in any examples files and the README.md that this Pull Request would represent. The versioning scheme we use is SemVer.
  5. You may merge the Pull Request once you have the sign-off of two other developers, or if you do not have permission to do that, you may request the second reviewer to merge it for you.

Issue Report Process

  1. Go to the project's issues.
  2. Select the template that better fits your issue.
  3. Read the instructions carefully and write within the template guidelines.
  4. Submit it and wait for support.

Commit Message Guidelines

When committing, commit messages are prefixed with one of the following depending on the type of change made.

  • feat: when a new feature is introduced with the changes.
  • fix: when a bug fix has occurred.
  • chore: for changes that do not relate to a fix or feature and do not modify source or tests. (like updating dependencies)
  • refactor: for refactoring code that neither fixes a bug nor adds a feature.
  • docs: when changes are made to documentation.
  • style: when changes that do not affect the code, but modify formatting.
  • test: when changes to tests are made.
  • perf: for changes that improve performance.
  • ci: for changes that affect CI.
  • build: for changes that affect the build system or external dependencies.
  • revert: when reverting changes.

Commit messages are also to begin with an uppercase character. Below list some example commit messages.

git commit -m "docs: Added README.md"
git commit -m "revert: Removed README.md"
git commit -m "docs: Moved README.md"

Code Quality

Testing

Please ensure that tests are updated and pass before merging a Pull Request.

# To test your code, run:
make test

Linting

We use Ruff, Gofmt and Prettier to ensure that code is consistent and follows our code style. Please ensure that your code passes linting before merging a Pull Request.

# To lint your code, run:
make lint

# To fix any linting errors, run:
make format