Mirrors/gotosocial
1
0
Fork 0
mirror of https://github.com/superseriousbusiness/gotosocial.git synced 2024-10-31 22:40:01 +00:00
Code Issues Projects Releases Packages Wiki Activity

[docs] Update CONTRIBUTING.md, add pull request templates (#1216)

Browse source 
* [docs] Update contributing.md

- Add Pull Request process and guidelines.
- Add feature/bug issue process.
- Rearrange some sections for clarity.
- Add overview of package structure.

* [docs] Add build from source links

* [chore] add pull request templates

These link to the new CONTRIBUTING.md document, and include a checklist to validate that contributors have read the guidelines.

* [docs] Put existing stub CoC in separate doc

* update web related stuff in CONTRIBUTING.md

Co-authored-by: f0x <f0x@cthu.lu>
This commit is contained in:
tobi 2022-12-09 11:53:58 +01:00 committed by GitHub
parent 199672e586
commit 610c2708ca
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
7 changed files with 412 additions and 241 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

15
.github/PULL_REQUEST_TEMPLATE/bugfix.md vendored Normal file
View file

@ -0,0 +1,15 @@
# Description
> Please include a summary of the change and which issue is fixed.
Fixes # (issue)
# Checklist:
- [ ] I have read the [GoToSocial contribution guidelines](https://github.com/superseriousbusiness/gotosocial/blob/main/CONTRIBUTING.md).
- [ ] I have performed a self-review of my own code.
- [ ] I have commented my code, particularly in hard-to-understand areas.
- [ ] I have made any necessary changes to documentation.
- [ ] New and existing tests pass locally with my changes.
- [ ] I have run `go fmt ./...` and `golangci-lint run`.
- [ ] I have added tests that prove my fix is effective.

3
.github/PULL_REQUEST_TEMPLATE/documentation.md vendored Normal file
View file

@ -0,0 +1,3 @@
# Description
> Please briefly explain the documentation change that you've made, and why.

16
.github/PULL_REQUEST_TEMPLATE/feature.md vendored Normal file
View file

@ -0,0 +1,16 @@
# Description
> Please include a summary of the feature you've coded, and link to the issue that it closes/implements.
Implements # (issue)
# Checklist:
- [ ] I have read the [GoToSocial contribution guidelines](https://github.com/superseriousbusiness/gotosocial/blob/main/CONTRIBUTING.md).
- [ ] I have discussed my implementation already, either in an issue on the repository, or in the Matrix chat.
- [ ] I have performed a self-review of my own code.
- [ ] I have commented my code, particularly in hard-to-understand areas.
- [ ] I have made any necessary changes to documentation.
- [ ] New and existing tests pass locally with my changes.
- [ ] I have run `go fmt ./...` and `golangci-lint run`.
- [ ] I have added tests that cover my new code.

9
CODE_OF_CONDUCT.md Normal file
View file

@ -0,0 +1,9 @@
# Code of Conduct
This document is currently a stub.
In lieu of a fuller code of conduct, here are a few ground rules.
1. We *DO NOT ACCEPT* PRs from right-wingers, Nazis, transphobes, homophobes, racists, harassers, abusers, white-supremacists, misogynists, tech-bros of questionable ethics. If that's you, politely fuck off somewhere else.
2. Any PR that moves GoToSocial in the direction of surveillance capitalism or other bad fediverse behavior will be rejected.
3. Don't spam the general chat too hard.

599
CONTRIBUTING.md
View file

@ -1,92 +1,102 @@
# Contributing <!-- omit in toc -->
# Contribution Guidelines <!-- omit in toc -->
Hey! Welcome to the CONTRIBUTING.md for GoToSocial :) Thanks for taking a look, that kicks ass.
This document will expand as the project expands, so for now, this is basically a stub.
These contribution guidelines were adapted from / inspired by those of Gitea (https://github.com/go-gitea/gitea/blob/main/CONTRIBUTING.md). Thanks Gitea!
Contributions are welcome at this point, since the API is fairly stable now and the structure is somewhat coherent.
## Table of Contents <!-- omit in toc -->
Check the [issues](https://github.com/superseriousbusiness/gotosocial/issues) to see if there's anything you fancy jumping in on.
## Table Of Contents <!-- omit in toc -->
- [Communications](#communications)
- [Code of Conduct](#code-of-conduct)
- [Setting up your development environment](#setting-up-your-development-environment)
- [Stylesheet / Web dev](#stylesheet--web-dev)
- [Introduction](#introduction)
- [Bug reports and feature requests](#bug-reports-and-feature-requests)
- [Pull requests](#pull-requests)
- [Code](#code)
- [Documentation](#documentation)
- [Development](#development)
- [Golang forking quirks](#golang-forking-quirks)
- [Setting up your test environment](#setting-up-your-test-environment)
- [Standalone Testrig with Pinafore](#standalone-testrig-with-pinafore)
- [Running automated tests](#running-automated-tests)
- [SQLite](#sqlite)
- [Postgres](#postgres)
- [Both](#both)
- [CLI Tests](#cli-tests)
- [Project Structure](#project-structure)
- [Style](#style)
- [Linting and Formatting](#linting-and-formatting)
- [Updating Swagger docs](#updating-swagger-docs)
- [CI/CD configuration](#cicd-configuration)
- [Release Checklist](#release-checklist)
- [What if something goes wrong?](#what-if-something-goes-wrong)
- [Building Docker containers](#building-docker-containers)
- [With GoReleaser](#with-goreleaser)
- [Manually](#manually)
- [Financial Compensation](#financial-compensation)
- [Building GoToSocial](#building-gotosocial)
- [Binary](#binary)
- [Docker](#docker)
- [With GoReleaser](#with-goreleaser)
- [Manually](#manually)
- [Stylesheet / Web dev](#stylesheet--web-dev)
- [Live Reloading](#live-reloading)
- [Project Structure](#project-structure)
- [Finding your way around the code](#finding-your-way-around-the-code)
- [Style / Linting / Formatting](#style--linting--formatting)
- [Testing](#testing)
- [Standalone Testrig with Pinafore](#standalone-testrig-with-pinafore)
- [Running automated tests](#running-automated-tests)
- [SQLite](#sqlite)
- [Postgres](#postgres)
- [CLI Tests](#cli-tests)
- [Updating Swagger docs](#updating-swagger-docs)
- [CI/CD configuration](#cicd-configuration)
- [Release Checklist](#release-checklist)
- [What if something goes wrong?](#what-if-something-goes-wrong)
## Communications
## Introduction
Before starting on something, please comment on an issue to say that you're working on it, and/or drop into the GoToSocial Matrix room [here](https://matrix.to/#/#gotosocial:superseriousbusiness.org).
This document contains important information that will help you to write a successful contribution to GoToSocial. Please read it carefully before opening a pull request!
This is the recommended way of keeping in touch with other developers, asking direct questions about code, and letting everyone know what you're up to.
## Bug reports and feature requests
## Code of Conduct
Currently, we use Github's issue system for tracking bug reports and feature requests.
In lieu of a fuller code of conduct, here are a few ground rules.
You can view all open issues [here](https://github.com/superseriousbusiness/gotosocial/issues "The Github Issues page for GoToSocial").
1. We *DO NOT ACCEPT* PRs from right-wingers, Nazis, transphobes, homophobes, racists, harassers, abusers, white-supremacists, misogynists, tech-bros of questionable ethics. If that's you, politely fuck off somewhere else.
2. Any PR that moves GoToSocial in the direction of surveillance capitalism or other bad fediverse behavior will be rejected.
3. Don't spam the general chat too hard.
Before opening a new issue, whether bug or feature request, **please search carefully through both open and closed issues to make sure it hasn't been addressed already**. You can use Github's keyword issue search for this. If your issue is a duplicate of an existing issue, it will be closed.
## Setting up your development environment
Before you open a feature request issue, please consider the following:
To get started, you first need to have Go installed. GtS is currently using Go 1.19, so you should take that too. See [here](https://golang.org/doc/install).
- Does this feature fit within the scope of GoToSocial? Since we are a small team, we are wary of [feature creep](https://en.wikipedia.org/wiki/Feature_creep "Wikipedia article on Feature Creep"), which can cause maintenance issues.
- Will this feature be generally useful for many users of the software, or is it handy for only a very specific use case?
- Will this feature have a negative impact on the performance of the software? If so, is the tradeoff worth it?
- Does this feature require loosening API security restrictions in some way? If so, it will need a good justification.
- Does this feature belong in GoToSocial's server backend, or is it something that a client could implement instead?
Once you've got go installed, clone this repository into your Go path. Normally, this should be `~/go/src/github.com/superseriousbusiness/gotosocial`.
We tend to prioritize feature requests related to accessibility, fedi interoperability, and client compatibility.
Once that's done, you can try building the project: `./scripts/build.sh`. This will build the `gotosocial` binary.
## Pull requests
If there are no errors, great, you're good to go!
We welcome pull requests from new and existing contributors, with the following provisos:
For automatic re-compiling during development, you can use [nodemon](https://www.npmjs.com/package/nodemon):
- You have read and agree to our Code of Conduct.
- The pull request addresses an existing issue or bug (please link to the relevant issue in your pull request), or is related to documentation.
- If your pull request introduces significant new code paths, you are willing to do some maintenance work on those code paths, and address bugs. We do not appreciate drive-by pull requests that introduce a significant maintenance burden!
- The pull request is of decent quality. We are a small team and unfortunately we don't have a lot of time to help shepherd pull requests, or help with basic coding questions. If you're unsure, don't bite off more than you can chew: start with a small feature or bugfix for your first PR, and work your way up.
```bash
nodemon -e go --signal SIGTERM --exec "go run ./cmd/gotosocial --host localhost testrig start || exit 1"
```
If you have small questions or comments before/during the pull request process, you can [join our Matrix space](https://matrix.to/#/#gotosocial-space:superseriousbusiness.org "GoToSocial Matrix space") at `#gotosocial-space:superseriousbusiness.org`.
### Stylesheet / Web dev
Please read the appropriate section below for the kind of pull request you plan to open.
To work with the stylesheet for templates, you need [Node.js](https://nodejs.org/en/download/) and [Yarn](https://classic.yarnpkg.com/en/docs/install).
### Code
To install Yarn dependencies:
To keep things manageable for maintainers, the process for opening pull requests against the GoToSocial repository works roughly as follows:
```bash
yarn install --cwd web/source
```
1. Open an issue for the feature, bug, or issue your pull request will address, or comment on an existing issue to let everyone know you want to work on it.
2. Use the open issue to discuss your design with us, gather feedback, and resolve any concerns about the implementation.
3. Write your code! Make sure all existing tests pass. Add tests where appropriate. Run linters and formatters. Update documentation.
4. Open your pull request. You can do this as a draft, if you want to gather more feedback on code-in-progress.
5. Let us know that your pull request is ready to be reviewed.
6. Wait for review.
7. Address review comments, make changes to the code where appropriate. It's OK to push back on review comments if you have a sensible reason--we're all learning, after all--but please do so with patience and grace.
8. Get your code merged, rejoice!
To recompile bundles:
To make your code easier to review, try to split your pull request into sensibly-sized commits, but don't worry too much about making it totally perfect: we always squash merge anyways.
```bash
BUDO_BUILD=1 node web/source
```
If your pull request ends up being massive, consider splitting it into smaller discrete pull requests to make it easier to review and reason about.
Or you can run live reloading in development. It will start a webserver (ip/port printed in console, default localhost:8081), while also keeping the bundles
up-to-date on disk. You can access the user/admin panels at localhost:8080/user, localhost:8080/admin, or run in tandem with the GoToSocial testrig, which will also
serve the updated bundles from disk.
Make sure your pull request only contains code that's relevant to the feature you're trying to implement, or the bug you're trying to address. Don't include refactors of unrelated parts of the code in your pull request: make a separate PR for that!
``` bash
NODE_ENV=development node web/source
```
If you open a code pull request without following the above process, we may close it and ask you to follow the process instead.
### Documentation
The process for documentation pull requests is a bit looser than the process for code.
If you see something in the documentation that's missing, wrong, or unclear, feel free to open a pull request addressing it; you don't necessarily need to open an issue first, but please explain why you're opening the PR in the PR comment.
## Development
### Golang forking quirks
@ -120,193 +130,29 @@ In case this post disappears, here are the steps (slightly modified):
> `git remote add origin git@github.com/yourgithubname/gotosocial`
>
## Setting up your test environment
### Building GoToSocial
GoToSocial provides a [testrig](https://github.com/superseriousbusiness/gotosocial/tree/main/testrig) with a number of mock packages you can use in integration tests.
#### Binary
One thing that *isn't* mocked is the Database interface because it's just easier to use an in-memory SQLite database than to mock everything out.
To get started, you first need to have Go installed. GtS is currently using Go 1.19, so you should take that too. See [here](https://golang.org/doc/install).
### Standalone Testrig with Pinafore
Once you've got go installed, clone this repository into your Go path. Normally, this should be `~/go/src/github.com/superseriousbusiness/gotosocial`.
You can launch a testrig as a standalone server running at localhost, which you can connect to using something like [Pinafore](https://github.com/nolanlawson/pinafore).
Once you've installed the prerequisites, you can try building the project: `./scripts/build.sh`. This will build the `gotosocial` binary.
To do this, first build the gotosocial binary with `./scripts/build.sh`.
If there are no errors, great, you're good to go!
Then, launch the testrig by invoking the binary as follows:
For automatic re-compiling during development, you can use [nodemon](https://www.npmjs.com/package/nodemon):
```bash
GTS_DB_TYPE="sqlite" GTS_DB_ADDRESS=":memory:" ./gotosocial --host localhost:8080 testrig start
nodemon -e go --signal SIGTERM --exec "go run ./cmd/gotosocial --host localhost testrig start || exit 1"
```
To run Pinafore locally in dev mode, first clone the [Pinafore](https://github.com/nolanlawson/pinafore) repository, and then run the following command in the cloned directory:
```bash
yarn run dev
```
The Pinafore instance will start running on `localhost:4002`.
To connect to the testrig, navigate to `http://localhost:4002` and enter your instance name as `localhost:8080`.
At the login screen, enter the email address `zork@example.org` and password `password`. You will get a confirmation prompt. Accept, and you are logged in as Zork.
Note the following constraints:
- Since the testrig uses an in-memory database, the database will be destroyed when the testrig is stopped.
- If you stop the testrig and start it again, any tokens or applications you created during your tests will also be removed. As such, you need to log out and in again every time you stop/start the rig.
- The testrig does not make any actual external HTTP calls, so federation will not work from a testrig.
### Running automated tests
There are a few different ways of running tests. Each requires the use of the `-p 1` flag, to indicate that they should not be run in parallel.
#### SQLite
If you would like to run tests as quickly as possible, using an SQLite in-memory database, use:
```bash
GTS_DB_TYPE="sqlite" GTS_DB_ADDRESS=":memory:" go test ./...
```
#### Postgres
If you want to run tests against a Postgres database running on localhost, run:
```bash
GTS_DB_TYPE="postgres" GTS_DB_ADDRESS="localhost" go test -p 1 ./...
```
In the above command, it is assumed you are using the default Postgres password of `postgres`.
#### Both
Finally, to run tests against both database types one after the other, use:
```bash
./scripts/test.sh
```
### CLI Tests
In [./test/envparsing.sh](./test/envparsing.sh) there's a test for making sure that CLI flags, config, and environment variables get parsed as expected.
Although this test *is* part of the CI/CD testing process, you probably won't need to worry too much about running it yourself. That is, unless you're messing about with code inside the `main` package in `cmd/gotosocial`, or inside the `config` package in `internal/config`.
## Project Structure
For project structure, GoToSocial follows a standard and widely accepted project layout [defined here](https://github.com/golang-standards/project-layout). As the author writes:
> This is a basic layout for Go application projects. It's not an official standard defined by the core Go dev team; however, it is a set of common historical and emerging project layout patterns in the Go ecosystem.
Most of the crucial business logic of the application is found inside the various packages and subpackages of the `internal` directory.
Where possible, we prefer more files and packages of shorter length that very clearly pertain to definable chunks of application logic, rather than fewer but longer files: if one `.go` file is pushing 1,000 lines of code, it's probably too long.
## Style
It is a good idea to read the short official [Effective Go](https://golang.org/doc/effective_go) page before submitting code: this document is the foundation of many a style guide, for good reason, and GoToSocial more or less follows its advice.
Another useful style guide that we try to follow: [this one](https://github.com/bahlo/go-styleguide).
In addition, here are some specific highlights from Uber's Go style guide which agree with what we try to do in GtS:
- [Group Similar Declarations](https://github.com/uber-go/guide/blob/master/style.md#group-similar-declarations).
- [Reduce Nesting](https://github.com/uber-go/guide/blob/master/style.md#reduce-nesting).
- [Unnecessary Else](https://github.com/uber-go/guide/blob/master/style.md#unnecessary-else).
- [Local Variable Declarations](https://github.com/uber-go/guide/blob/master/style.md#local-variable-declarations).
- [Reduce Scope of Variables](https://github.com/uber-go/guide/blob/master/style.md#reduce-scope-of-variables).
- [Initializing Structs](https://github.com/uber-go/guide/blob/master/style.md#initializing-structs).
## Linting and Formatting
Before you submit any code, make sure to run `go fmt ./...` to update whitespace and other opinionated formatting.
We use [golangci-lint](https://golangci-lint.run/) for linting, which allows us to catch style inconsistencies and potential bugs or security issues, using static code analysis.
If you make a PR that doesn't pass the linter, it will be rejected. As such, it's good practice to run the linter locally before pushing or opening a PR.
To do this, first install the linter following the instructions [here](https://golangci-lint.run/usage/install/#local-installation).
Then, you can run the linter with:
```bash
golangci-lint run
```
If there's no output, great! It passed :).
## Updating Swagger docs
GoToSocial uses [go-swagger](https://goswagger.io) to generate Swagger API documentation from code annotations.
You can install go-swagger following the instructions [here](https://goswagger.io/install.html).
If you change Swagger annotations on any of the API paths, you can generate a new Swagger file at `./docs/api/swagger.yaml` by running:
```bash
swagger generate spec --scan-models --exclude-deps -o docs/api/swagger.yaml
```
## CI/CD configuration
GoToSocial uses [Drone](https://www.drone.io/) for CI/CD tasks like running tests, linting, and building Docker containers.
These runs are integrated with GitHub, and will be run on opening a pull request or merging into main.
The Drone instance for GoToSocial is [here](https://drone.superseriousbusiness.org/superseriousbusiness/gotosocial).
The `drone.yml` file is [here](./.drone.yml) — this defines how and when Drone should run. Documentation for Drone is [here](https://docs.drone.io/).
It is worth noting that the `drone.yml` file must be signed by the Drone admin account to be considered valid. This must be done every time the file is changed. This is to prevent tampering and hijacking of the Drone instance. See [here](https://docs.drone.io/signature/).
To sign the file, first install and setup the [drone cli tool](https://docs.drone.io/cli/install/). Then, run:
```bash
drone -t PUT_YOUR_DRONE_ADMIN_TOKEN_HERE -s https://drone.superseriousbusiness.org sign superseriousbusiness/gotosocial --save
```
## Release Checklist
First things first: If this is a security hot-fix, we'll probably rush through this list, and make a prettier release a few days later.
Now, with that out of the way, here's our Checklist.
GoToSocial follows [Semantic Versioning](https://semver.org/).
So our first concern on the Checklist is:
- What version are we releasing?
Next we need to check:
- Do the assets have to be rebuilt and committed to the repository.
- Do the swagger docs have to be rebuilt?
On the project management side:
- Are there any issues that have to be moved to a different milestone?
- Are there any things on the [Roadmap](./ROADMAP.md) that can be ticked off?
Once we're happy with our Checklist, we can create the tag, and push it.
And the rest [is automation](./.drone.yml).
We can now head to GitHub, and add some personality to the release notes.
Finally, we make announcements on the all our channels that the release is out!
### What if something goes wrong?
Sometimes things go awry.
We release a buggy release, we forgot something ­ something important.
If the release is so bad that it's unusable ­ or dangerous! ­ to a great part of our user-base, we can pull.
That is: Delete the tag.
Either way, once we've resolved the issue, we just start from the top of this list again. Version numbers are cheap. It's cheap to burn them.
## Building Docker containers
#### Docker
For both of the below methods, you need to have [Docker buildx](https://docs.docker.com/buildx/working-with-buildx/) installed.
### With GoReleaser
##### With GoReleaser
GoToSocial uses the release tooling [GoReleaser](https://goreleaser.com/intro/) to make multiple-architecture + Docker builds simple.
@ -328,7 +174,7 @@ goreleaser --rm-dist --snapshot
If all goes according to plan, you should now have a number of multiple-architecture binaries and tars inside the `./dist` folder, and snapshot Docker images should be built (check your terminal output for version).
### Manually
##### Manually
If you prefer a simple approach to building a Docker container, with fewer dependencies (go-swagger, Node, Yarn), you can also just build in the following way:
@ -358,8 +204,281 @@ See also: [exhaustive list of GOOS and GOARCH values](https://gist.github.com/li
And: [exhaustive list of possible values for docker's `--platform`](https://github.com/tonistiigi/binfmt/#build-test-image)
## Financial Compensation
### Stylesheet / Web dev
Right now, there's no structure in place for financial compensation for pull requests and code. This is simply because there's no money being made on the project, apart from the very small weekly Liberapay donations.
GoToSocial uses Gin templates in the `web/template` folder. Static assets are stored in `web/assets`. Source files for stylesheets and JS bundles (for frontend enhancement, and the settings interface) are stored in `web/source`, and bundled from there to the `web/assets/dist` folder (gitignored).
If money starts coming in, I'll start looking at proper financial structures, but for now, code is considered to be a donation in itself.
To bundle changes, you need [Node.js](https://nodejs.org/en/download/) and [Yarn](https://classic.yarnpkg.com/en/docs/install).
To install Yarn dependencies:
```bash
yarn install --cwd web/source
```
To recompile bundles:
```bash
node web/source
```
#### Live Reloading
For a more convenient development environment, you can run a livereloading version of the bundler alongside the [testrig](#testing).
Open two terminals, first start the testrig on port 8081:
``` bash
GTS_PORT=8081 go run ./cmd/gotosocial testrig start
```
Then start the bundler, which will run on port 8080, and proxy requests to the testrig instance where needed.
``` bash
NODE_ENV=development node web/source
```
The livereloading bundler *will not* change the bundled assets in `dist/`, so once you are finished with changes and want to deploy it somewhere, you have to run `node web/source` to generate production-ready bundles.
### Project Structure
For project structure, GoToSocial follows a standard and widely accepted project layout [defined here](https://github.com/golang-standards/project-layout). As the author writes:
> This is a basic layout for Go application projects. It's not an official standard defined by the core Go dev team; however, it is a set of common historical and emerging project layout patterns in the Go ecosystem.
Where possible, we prefer more files and packages of shorter length that very clearly pertain to definable chunks of application logic, rather than fewer but longer files: if one `.go` file is pushing 1,000 lines of code, it's probably too long.
#### Finding your way around the code
Most of the crucial business logic of the application is found inside the various packages and subpackages of the `internal` directory. Here's a brief summary of each of these:
`internal/ap` - ActivityPub utility functions and interfaces.
`internal/api` - Models, routers, and utilities for the client and federated (s2s) APIs. This is where routes are attached to the router, and where you want to be if you're adding a route.
`internal/concurrency` - Worker models used by the processor and other queues.
`internal/config` - Code for configuration flags, CLI flag parsing, and getting/setting config.
`internal/db` - DB interfaces for interacting with sqlite/postgres databases. Database migration code is in `internal/db/bundb/migrations`.
`internal/email` - Email functionality, email sending via SMTP.
`internal/federation` - ActivityPub federation code; implements `go-fed` interfaces.
`internal/federation/federatingdb` - Implementation of `go-fed`'s Database interface.
`internal/federation/dereferencing` - Code for making http calls to fetch resources from remote instances.
`internal/gotosocial` - GoToSocial server startup/shutdown logic.
`internal/gtserror` - Error models.
`internal/gtsmodel` - Database and internal models. This is where `bundb` annotations live.
`internal/httpclient` - The HTTP client used by GoToSocial for making requests to remote resources.
`internal/id` - Code for generating IDs (ULIDs) for database models.
`internal/log` - Our logging implementation.
`internal/media` - Code related to managing + processing media attachments; images, video, emojis, etc.
`internal/messages` - Models for wrapping worker messages.
`internal/netutil` - HTTP / net request validation code.
`internal/oauth` - Wrapper code/interfaces for OAuth server implementation.
`internal/oidc` - Wrapper code/interfaces for OIDC claims and callbacks.
`internal/processing` - Logic for processing messages produced by the federation or client APIs. Much of the core business logic of GoToSocial is contained here.
`internal/regexes` - Regular expressions used for text parsing and matching of URLs, hashtags, mentions, etc.
`internal/router` - Wrapper for Gin HTTP router. Core HTTP logic is contained here. The router exposes functions for attaching routes, which are used by the code in `internal/api` handlers.
`internal/storage` - Wrapper for `codeberg.org/gruf/go-store` implementations. Local file storage and s3 logic goes here.
`internal/stream` - Websockets streaming logic.
`internal/text` - Text parsing and transformation. Status parsing logic is contained here -- both plain and markdown.
`internal/timeline` - Status timeline management code.
`internal/trans` - Code for exporting models to json backup files from the database, and importing backup json files into the database.
`internal/transport` - HTTP transport code and utilities.
`internal/typeutils` - Code for converting from internal database models to json, and back, or from ActivityPub format to internal database model format and vice versa. Basically, serdes.
`internal/uris` - Utilities for generating URIs used throughout GoToSocial.
`internal/util` - Odds and ends; small utility functions used by more than one package.
`internal/validate` - Model validation code -- currently not really used.
`internal/visibility` - Status visibility checking and filtering.
`internal/web` - Web UI handlers, specifically for serving web pages, the landing page, settings panels.
### Style / Linting / Formatting
It is a good idea to read the short official [Effective Go](https://golang.org/doc/effective_go) page before submitting code: this document is the foundation of many a style guide, for good reason, and GoToSocial more or less follows its advice.
Another useful style guide that we try to follow: [this one](https://github.com/bahlo/go-styleguide).
In addition, here are some specific highlights from Uber's Go style guide which agree with what we try to do in GtS:
- [Group Similar Declarations](https://github.com/uber-go/guide/blob/master/style.md#group-similar-declarations).
- [Reduce Nesting](https://github.com/uber-go/guide/blob/master/style.md#reduce-nesting).
- [Unnecessary Else](https://github.com/uber-go/guide/blob/master/style.md#unnecessary-else).
- [Local Variable Declarations](https://github.com/uber-go/guide/blob/master/style.md#local-variable-declarations).
- [Reduce Scope of Variables](https://github.com/uber-go/guide/blob/master/style.md#reduce-scope-of-variables).
- [Initializing Structs](https://github.com/uber-go/guide/blob/master/style.md#initializing-structs).
Before you submit any code, make sure to run `go fmt ./...` to update whitespace and other opinionated formatting.
We use [golangci-lint](https://golangci-lint.run/) for linting, which allows us to catch style inconsistencies and potential bugs or security issues, using static code analysis.
If you make a PR that doesn't pass the linter, it will be rejected. As such, it's good practice to run the linter locally before pushing or opening a PR.
To do this, first install the linter following the instructions [here](https://golangci-lint.run/usage/install/#local-installation).
Then, you can run the linter with:
```bash
golangci-lint run
```
If there's no output, great! It passed :)
### Testing
GoToSocial provides a [testrig](https://github.com/superseriousbusiness/gotosocial/tree/main/testrig) with a number of mock packages you can use in integration tests.
One thing that *isn't* mocked is the Database interface because it's just easier to use an in-memory SQLite database than to mock everything out.
#### Standalone Testrig with Pinafore
You can launch a testrig as a standalone server running at localhost, which you can connect to using something like [Pinafore](https://github.com/nolanlawson/pinafore).
To do this, first build the gotosocial binary with `./scripts/build.sh`.
Then, launch the testrig by invoking the binary as follows:
```bash
./gotosocial testrig start
```
To run Pinafore locally in dev mode, first clone the [Pinafore](https://github.com/nolanlawson/pinafore) repository, and then run the following command in the cloned directory:
```bash
yarn run dev
```
The Pinafore instance will start running on `localhost:4002`.
To connect to the testrig, navigate to `http://localhost:4002` and enter your instance name as `localhost:8080`.
At the login screen, enter the email address `zork@example.org` and password `password`. You will get a confirmation prompt. Accept, and you are logged in as Zork.
Note the following constraints:
- Since the testrig uses an in-memory database, the database will be destroyed when the testrig is stopped.
- If you stop the testrig and start it again, any tokens or applications you created during your tests will also be removed. As such, you need to log out and in again every time you stop/start the rig.
- The testrig does not make any actual external HTTP calls, so federation will not work from a testrig.
#### Running automated tests
Tests can be run against both SQLite and Postgres.
##### SQLite
If you would like to run tests as quickly as possible, using an SQLite in-memory database, use:
```bash
go test ./...
```
##### Postgres
If you want to run tests against a Postgres database on localhost, run:
```bash
GTS_DB_TYPE="postgres" GTS_DB_ADDRESS="localhost" go test -p 1 ./...
```
In the above command, it is assumed you are using the default Postgres password of `postgres`.
We set `-p 1` when running against Postgres because it requires tests to run in serial, not in parallel.
#### CLI Tests
In [./test/envparsing.sh](./test/envparsing.sh) there's a test for making sure that CLI flags, config, and environment variables get parsed as expected.
Although this test *is* part of the CI/CD testing process, you probably won't need to worry too much about running it yourself. That is, unless you're messing about with code inside the `main` package in `cmd/gotosocial`, or inside the `config` package in `internal/config`.
### Updating Swagger docs
GoToSocial uses [go-swagger](https://goswagger.io) to generate Swagger API documentation from code annotations.
You can install go-swagger following the instructions [here](https://goswagger.io/install.html).
If you change Swagger annotations on any of the API paths, you can generate a new Swagger file at `./docs/api/swagger.yaml` by running:
```bash
swagger generate spec --scan-models --exclude-deps -o docs/api/swagger.yaml
```
### CI/CD configuration
GoToSocial uses [Drone](https://www.drone.io/) for CI/CD tasks like running tests, linting, and building Docker containers.
These runs are integrated with GitHub, and will be run on opening a pull request or merging into main.
The Drone instance for GoToSocial is [here](https://drone.superseriousbusiness.org/superseriousbusiness/gotosocial).
The `drone.yml` file is [here](./.drone.yml) — this defines how and when Drone should run. Documentation for Drone is [here](https://docs.drone.io/).
It is worth noting that the `drone.yml` file must be signed by the Drone admin account to be considered valid. This must be done every time the file is changed. This is to prevent tampering and hijacking of the Drone instance. See [here](https://docs.drone.io/signature/).
To sign the file, first install and setup the [drone cli tool](https://docs.drone.io/cli/install/). Then, run:
```bash
drone -t PUT_YOUR_DRONE_ADMIN_TOKEN_HERE -s https://drone.superseriousbusiness.org sign superseriousbusiness/gotosocial --save
```
### Release Checklist
First things first: If this is a security hot-fix, we'll probably rush through this list, and make a prettier release a few days later.
Now, with that out of the way, here's our Checklist.
GoToSocial follows [Semantic Versioning](https://semver.org/).
So our first concern on the Checklist is:
- What version are we releasing?
Next we need to check:
- Do the assets have to be rebuilt and committed to the repository.
- Do the swagger docs have to be rebuilt?
On the project management side:
- Are there any issues that have to be moved to a different milestone?
- Are there any things on the [Roadmap](./ROADMAP.md) that can be ticked off?
Once we're happy with our Checklist, we can create the tag, and push it.
And the rest [is automation](./.drone.yml).
We can now head to GitHub, and add some personality to the release notes.
Finally, we make announcements on the all our channels that the release is out!
#### What if something goes wrong?
Sometimes things go awry.
We release a buggy release, we forgot something ­ something important.
If the release is so bad that it's unusable ­ or dangerous! ­ to a great part of our user-base, we can pull.
That is: Delete the tag.
Either way, once we've resolved the issue, we just start from the top of this list again. Version numbers are cheap. It's cheap to burn them.

7
README.md
View file

@ -10,7 +10,7 @@ With GoToSocial, you can keep in touch with your friends, post, read, and share
**GoToSocial is still [ALPHA SOFTWARE](https://en.wikipedia.org/wiki/Software_release_life_cycle#Alpha)**. It is already deployable and useable, and it federates cleanly with many other Fediverse servers (not yet all). However, many things are not yet implemented, and there are plenty of bugs! We foresee entering beta somewhere in 2023.
Documentation is at [docs.gotosocial.org](https://docs.gotosocial.org). You can skip straight to the API documentation [here](https://docs.gotosocial.org/en/latest/api/swagger/).
Documentation is at [docs.gotosocial.org](https://docs.gotosocial.org). You can skip straight to the API documentation [here](https://docs.gotosocial.org/en/latest/api/swagger/). To build from source, check the [CONTRIBUTING.md](./CONTRIBUTING.md) file.
Here's a screenshot of the instance landing page!
@ -37,6 +37,7 @@ Here's a screenshot of the instance landing page!
- [Client App Issues](#client-app-issues)
- [Federation Issues](#federation-issues)
- [Contributing](#contributing)
- [Building](#building)
- [Contact](#contact)
- [Credits](#credits)
- [Libraries](#libraries)
@ -193,6 +194,10 @@ Since every ActivityPub server implementation has a slightly different interpret
You would like to contribute to GtS? Great! ❤️❤️❤️ Check out the issues page to see if there's anything you intend to jump in on, and read the [CONTRIBUTING.md](./CONTRIBUTING.md) file for guidelines and setting up your dev environment.
## Building
Instructions for building GoToSocial from source are in the [CONTRIBUTING.md](./CONTRIBUTING.md) file.
## Contact
For questions and comments, you can [join our Matrix space](https://matrix.to/#/#gotosocial-space:superseriousbusiness.org) at `#gotosocial-space:superseriousbusiness.org`. This is the quickest way to reach the devs. You can also mail [admin@gotosocial.org](mailto:admin@gotosocial.org).

4
docs/index.md
View file

@ -48,6 +48,10 @@ Since every ActivityPub server implementation has a slightly different interpret
You wanna contribute to GtS? Great! ❤️❤️❤️ Check out the issues page to see if there's anything you wanna jump in on, and read the CONTRIBUTING.md file on the repository for guidelines and setting up your dev environment.
## Building
Instructions for building GoToSocial from source are also in the CONTRIBUTING.md file.
## Contact
For questions and comments, you can [join our Matrix channel](https://matrix.to/#/#gotosocial:superseriousbusiness.org) at `#gotosocial:superseriousbusiness.org`. This is the quickest way to reach the devs. You can also mail [admin@gotosocial.org](mailto:admin@gotosocial.org).