From 24c402523aa027eb03157f515d8c5d2a4b13dc68 Mon Sep 17 00:00:00 2001 From: Tom Meadows Date: Tue, 12 Dec 2023 17:37:27 +0000 Subject: [PATCH] changes / suggested improvements on CONTRIBUTING.md --- CONTRIBUTING.md | 86 +++++++++++++++++++++++++++++-------------------- 1 file changed, 51 insertions(+), 35 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c624aec2..34ee6780 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -3,7 +3,7 @@ We welcome contributions from the community and first want to thank you for taking the time to contribute! -Please familiarize yourself with the [Code of Conduct](CODE_OF_CONDUCT.md) +Before starting, please take some time to familiarize yourself with the [Code of Conduct](CODE_OF_CONDUCT.md). ## Getting started @@ -19,17 +19,53 @@ Pull Request. Contributions may include: * Helping to onboard new contributors * Other related activities -### Detailed installation instructions +### Setting up your environment + +### Required Tooling +Some tools are required on your system in order to help you with +the development process: + +* Git: Archivista is hosted on GitHub, so you will need to have Git installed. For + more information, please follow [this guide](https://github.com/git-guides/install-git). + +* GNU Make: The root of the directory contains a `Makefile` for automating development + processes. The `make` CLI tool is usually installed by default on most systems + (excluding Windows), but you can check if it is installed by running `make --version` + on your terminal. If this command is unsuccessful, you will need to find the standard + method for installing it for your system. For installing `make` on Windows, please see + [here](https://gnuwin32.sourceforge.net/packages/make.html). + +* Go v1.19: Archivista is written in [Go](https://golang.org/), so you + will need this installed in order to compile and run the source code. + +* pre-commit: It is a framework for managing and maintaining multi-language + pre-commit hooks. It is used to run some checks on the code before it is + committed. You can install it by following the instructions + [here](https://pre-commit.com/#install). + +* jq: It is a lightweight and flexible command-line JSON processor. It is + used to parse JSON files. You can install it by following the instructions + [here](https://stedolan.github.io/jq/download/). + +* A Container Runtime: Archivista is a container-based tool, and therefore you might + need a container runtime tool installed for development. The most common solution + for this is [Docker](https://docs.docker.com/engine/install/), however this is not + free on all platforms. If you are using MacOS, [Colima](https://github.com/abiosoft/colima) + is a free good alternative, as well as [Rancher Desktop](https://github.com/rancher-sandbox/rancher-desktop). + Please note that Archivista is not tested on these alternative tools, so compatibility + is not guaranteed. #### Getting the Archivista source code [Fork](https://docs.github.com/en/get-started/quickstart/fork-a-repo>) the repository on GitHub and [clone](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) it to -your local machine: - +your local machine: ```console git clone git@github.com:YOUR-USERNAME/archivista.git ``` +*The command above uses SSH to clone the repository, which we recommend. You can find out more +about how to set SSH up with Github [here](https://docs.github.com/en/authentication/connecting-to-github-with-ssh).* + Add a [remote](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/configuring-a-remote-for-a-fork) and regularly [sync](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork) to make sure @@ -42,49 +78,29 @@ you stay up-to-date with our repository: git merge upstream/main ``` -#### Setting up your environment +### Running Archivista Development Environment -Archivista is written in [Go](https://golang.org/). You will need to have Go. - -Archivista runs using Container and we provide some shortucts to help you -during the development process. - -Some tools are required to be installed on your system to help you with -the easy development process. You can install them: - -* pre-commit: It is a framework for managing and maintaining multi-language - pre-commit hooks. It is used to run some checks on the code before - committing it. You can install it by following the instructions - [here](https://pre-commit.com/#install). - -* jq: It is a lightweight and flexible command-line JSON processor. It is - used to parse JSON files. You can install it by following the instructions - [here](https://stedolan.github.io/jq/download/). - -* Docker Engine: It is used to build and run the Archivista container. You - can install it by following the instructions - [here](https://docs.docker.com/engine/install/). - -### Running Archivista Developement Environment - -Archivista uses Docker to run the development environment. You can run the command: +*Please note that the following `make` commands make use of both the `docker` and +`docker-compose` commands, so you may need to modify this locally if using tools +such as [nerdctl](https://github.com/containerd/nerdctl) or [podman](https://github.com/containers/podman).* +To start the Archivista development environment, simply execute the command: ```console make run-dev ``` - -This will run the Archivista container and its required dependencies services. +This will run the Archivista container and its required dependent services. Archivista will be available at http://localhost:8082 -Any change in the code will be automatically reflected in the container. +Any changes made to the source code will be reflected in the development environment +while it is running, so there is no need to restart it. -To stop the running containers, run the command: +To stop the development environment, run: ```console make stop ``` -To clean all Archivista containers in your environment run the command: +To clean all Archivista containers in your environment execute the command: ```console make clean @@ -93,7 +109,7 @@ To clean all Archivista containers in your environment run the command: ### Running Tests -You can run all the tests by running the command: +You can run all the tests by executing the command: ```console make test