Contribute

This documentation is a work in progress

The current state of this documentation is out-dated.
We're moving to Wails v3 alpha and much of this documentation will change.

Thanks for checking out the Bunkr App! We're excited to hear and learn from you.
We've put together the following guidelines to help you figure out where you can best be helpful.

Types of contributions we're looking for

There are many ways you can directly contribute to Bunkr (in descending order of need):

Interested in contributing to Bunkr? Read on!

Ground rules & expectations

Before we get started, here are a few things we expect from you (and that you should expect from others):

Be kind and thoughtful in your conversations around this project. We all come from different backgrounds and projects, which means we likely have different perspectives on "how open source is done." Try to listen to others rather than convince them that your way is correct.
Open Source Guides are released with a Contributor Code of Conduct. By participating in this project, you agree to abide by its terms.
Please ensure that your contribution passes all tests if you open a pull request. If there are test failures, you will need to address them before we can merge your contribution.

How to contribute

Start by searching through the pull requests to see whether someone else has raised a similar idea or question.

If you don't see your idea listed, and you think it fits into the goals of this project, open a pull request.

If you're not sure whether your idea fits into the goals of this project, you can open a discussion.

Style guide

If you're contributing code please make sure it conforms to the style guide.

Linting

To keep our code consistent and readable, we use GolangCI-Lint to lint our Go code.
The linters are run automatically on every push to a branch with an active PR.
The CI job is defined in .github/workflows/lint.yml.
The linters used are defined in the .golangci.yml file inside the src directory.
To get more information about each linter, check out the GolangCI-Lint docs.

Running the linters locally

To run the linters locally, you need to have GolangCI-Lint installed.
Navigate to the src directory and run:

golangci-lint run

Setup

This guide will walk you through setting up your development environment for Bunkr. Since everyones setup is different, we'll try to keep this guide as general as possible. If you run into any issues, please open an issue and we'll do our best to improve this guide.

Prerequisites

Git
Go	See go.mod for required version.
npm	Node 15 or higher
Wails	Checkout the official docs for installation instructions. You can find the required version of Wails in go.mod.
SqlC	Generates our database boilerplate code from SQL schema and query definitions.
templ	Used to generate our frontend templates.
optional but recommended
VS Code	A code editor.
VS Code Extensions	See [extensions.json](https://github.com/bunkr-dev/app/blob/main/.vscode/extensions.json).
GolangCI-Lint	A collection of Go linters we use to improve code quality and ensure consistency.

Getting Started

Clone the repository.

git clone git@github.com:bunkr-dev/app.git

Install Go dependencies.
```
cd src
go mod download
```
Generate code. (Database, Views, etc.)
```
go generate  
```
Install npm dependencies.
```
cd src/frontend
npm install
```
Run the app from the src directory.
```
wails dev
```

🎉 You should now have a working Bunkr app running on your machine!

Testing

We try to keep our testing workflow as simple as possible for the developers.
We use Playwright as our testing framework.
You can find all the tests in the e2e folder.
We try and follow a test driven development approach, but not on a unit test level.
The idea is not to have a test for every small function, but to have a test for every feature.
"It doesn't matter how the app is working, as long as its working."

Setup

To run the tests you'll have to install the dependencies first.
You'll need to have Node.js installed.
Then run the following command in the e2e folder of the project:

npm install

and

npx playwright install

Writing tests

:::note Under construction This section is still under construction. :::

Running tests

:::info Make sure you don't have the app or dev mode running when you run the tests. ::: To run the tests you simply have to execute the appropriate script for your OS.
scripts/run_tests_mac.sh for macOS
scripts/run_tests_win.ps1 for Windows
:::note Not implemented scripts/run_tests_linux.sh for Linux :::

This will do a few things for you automatically: - Delete any pervious dev builds. - Build the app in dev mode. - Create a copy of the dev build for testing. - Stop the dev build. - Build and start a small Go helper server on localhost:3333.
This takes care of starting and stopping Bunkr during the tests. - Open the playwright test UI.
This is where you have to take action again and choose which tests to run.
When you're done, you can close the UI and the script will continue. - Stop the helper server. - Delete the dev build copy.

Building

From the src directory, run:

wails build

You can find the built binaries in src/build/bin.

Community

Discussions about Bunkr take place in its GitHub repository's Issues, Pull Requests and Discussions.
Anybody is welcome to join these conversations.

Wherever possible, do not take these conversations to private channels, including contacting the maintainers directly. Keeping communication public means everybody can benefit and learn from the conversation.

Development

Setup

Checkout the setup guide for instructions on how to get started with development.

Fix a Bug 🚧

Add an Integration 🚧

Add a Feature 🚧

Improve the Documentation 🚧

Architecture

Database

We are using the Golang standard libraries database/sql to manage our db connections.
This allows us to use any database driver that implements the interface.
For now we are using modernc.org/sqlite for SQLite3.

Logging

We are using golang.org/x/slog for logging.
A reusable logger is created in internal/log.
This should be used in all packages.
It will log to stderr and to a .json file ~/.bunkr/log/bunkr.log.json.
This global logger will also take care of log file rotation.
A new log file will be created on every startup.
The old log file will be renamed to bunkr.log.json.1.
A maximum of 5 log files will be kept.
Old log files will be deleted on startup.

Frontend

We are using Go's html/template for server-side rendering of HTML. This allows us to dynamically generate HTML pages on the server-side based on the data we have. For client-side interactivity, we are using htmx and hyperscript. htmx allows us to access AJAX, CSS Transitions, WebSockets and Server Sent Events directly in HTML, enabling us to keep our frontend code simple and declarative. Hyperscript complements this by providing a mechanism to handle complex client-side logic in a simple and maintainable way. This combination allows us to create a rich, interactive user experience with minimal complexity.