docs: add contribution guide (#1368)

* docs: add CONTRIBUTING.md

* add nodejs version comment
fix frontend start command
add make build command section
capitalization
formatting

---------

Co-authored-by: martylukyy <35452459+martylukyy@users.noreply.github.com>
This commit is contained in:
ze0s 2024-01-23 17:08:17 +01:00 committed by GitHub
parent ae4427175f
commit 415cf7b6c1
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
2 changed files with 191 additions and 0 deletions

189
CONTRIBUTING.md Normal file
View file

@ -0,0 +1,189 @@
# Contributing to autobrr
Thanks for taking interest in contribution! We welcome anyone who wants to contribute.
If you have an idea for a bigger feature or a change then we are happy to discuss it before you start working on it.
It is usually a good idea to make sure it aligns with the project and is a good fit.
Open an issue or post in #dev-general on [Discord](https://discord.gg/WQ2eUycxyT).
This document is a guide to help you through the process of contributing to autobrr.
## Become a contributor
* Code: new features, bug fixes, improvements
* Report bugs
* Documentation: The docs repo can be found here: [github.com/autobrr/autobrr.com](https://github.com/autobrr/autobrr.com)
## Developer guide
This guide helps you get started developing autobrr.
## Dependencies
Make sure you have the following dependencies installed before setting up your developer environment:
- [Git](https://git-scm.com/)
- [Go](https://golang.org/dl/) (see [go.mod](go.mod#L3) for minimum required version)
- [Node.js](https://nodejs.org) (we usually use the latest Node LTS version - for further information see `@types/node` major version in [package.json](web/package.json))
- [pnpm](https://pnpm.io/installation)
## How to contribute
- **Fork and Clone:** [Fork the autobrr repository](https://github.com/autobrr/autobrr/fork) and clone it to start working on your changes.
- **Branching:** Create a new branch for your changes. Use a descriptive name for easy understanding.
- Checkout a new branch for your fix or feature `git checkout -b fix/filters-issue`
- **Coding:** Ensure your code is well-commented for clarity. With go use `go fmt`
- **Commit Guidelines:** We appreciate the use of [Conventional Commit Guidelines](https://www.conventionalcommits.org/en/v1.0.0/#summary) when writing your commits.
- Examples: `fix(indexers): Mock improve parsing`, `feat(notifications): add NewService`
- There is no need for force pushing or rebasing. We squash commits on merge to keep the history clean and manageable.
- **Pull Requests:** Submit a pull request from your Fork with a clear description of your changes. Reference any related issues.
- Mark it as Draft if it's still in progress.
- **Code Review:** Be open to feedback during the code review process.
## Development environment
The backend is written in Go and the frontend is written in TypeScript using React.
You need to have the Go toolchain installed and Node.js with `pnpm` as the package manager.
Clone the project and change dir:
```shell
git clone github.com/YOURNAME/autobrr && cd autobrr
```
## Frontend
First install the web dependencies:
```shell
cd web && pnpm install
```
Run the project:
```shell
pnpm dev
```
This should make the frontend available at [http://localhost:3000](http://localhost:3000). It's setup to communicate with the API at [http://localhost:7474](http://localhost:7474).
### Build
In order to build binaries of the full application you need to first build the frontend.
To build the frontend, run:
```shell
pnpm --dir web run build
```
## Backend
Install Go dependencies:
```shell
go mod tidy
```
Run the project:
```shell
go run cmd/autobrr/main.go
```
This uses the default `config.toml` and runs the API on [http://localhost:7474](http://localhost:7474).
### Build
To build the backend, run:
```shell
make build/app
```
This will output a binary in `./bin/autobrr`
You can also build the frontend and the backend at once with:
```shell
make build
```
### Build cross-platform binaries
You can optionally build it with [GoReleaser](https://goreleaser.com/) which makes it easy to build cross-platform binaries.
Install it with `go install` or check the [docs for alternatives](https://goreleaser.com/install/):
```shell
go install github.com/goreleaser/goreleaser@latest
```
Then to build binaries, run:
```shell
goreleaser build --snapshot --clean
```
## Tests
The test suite consists of only backend tests at this point. All tests run per commit with GitHub Actions.
### Run backend tests
We have a mix of unit and integration tests.
Run all non-integration tests:
```shell
go test -v ./...
```
### Run SQLite and PostgreSQL integration tests
The integration tests runs against an in memory SQLite database and currently requires Docker for the Postgres tests.
If you have docker setup then run the `test_postgres` container with:
```shell
docker compose up -d test_postgres
```
Then run all tests:
```shell
go test ./... -tags=integration
```
## Build Docker image
To build a Docker image, run:
```shell
make build/docker
```
The image will be tagged as `autobrr:dev`
## Mock indexer
We have a mock indexer you can run locally that features:
* Built in IRC server that can send announces
* Mock indexer for downloads
* RSS feed mock
* Webhook mock for External Filters
See the documentation [here](./test/mockindexer/README.md). Add the `customDefinitions` to the `config.toml` and then run it with:
```shell
go run test/mockindexer/main.go
```
* Restart the backend API for it to load the new mock.yaml definition
* Then add it via Settings -> Indexers -> Add, and select Mock Indexer in the list
* Go to Settings -> IRC and toggle the IRC network `Mock Indexer`
* Add a new Filter or add the indexer to an existing filter
* Open a new tab and navigate to [http://localhost:3999](http://localhost:3999) and put the example announce in the input then hit enter

View file

@ -293,6 +293,8 @@ Whether you're fixing a bug, adding a feature, or improving documentation, your
### Code Contributions
Check out the full guide for contributing [here](CONTRIBUTING.md).
- **Fork and Clone:** Fork the `autobrr` repository and clone it to start working on your changes.
- **Branching:** Create a new branch for your changes. Use a descriptive name for easy understanding.
- **Coding:** Ensure your code is well-commented for clarity.