This is a back up of Ryaina's earlier post since she is stepping away from the development team.

Hi everyone! Here is the promised post on how to contribute.

Contributing

Development discussions can be done on !hexbear@hexbear.net (essentially our own little stackoverflow) or the issue trackers at git.chapo.chat where appropriate.

We also have a matrix server and room.

https://matrix.chapo.chat is the home server address but it is configure to user the toplevel chapo.chat domain. Setting your homeserver to https://chapo.chat should work in most cases but where the client doesn't properly support the .wellknown directives you will have to use the full address.

create a user account on our homeserver and join the #hexbear-dev:chapo.chat room!
https://matrix.to/#/#hexbear-dev:chapo.chat

To contribute you'll need Git and knowledge on the basics of its use, some git credentials, and a Gitea account.

You can log into git.chapo.chat any one of three ways

  • Create a GitHub or GitLab and sign in with it.
  • Or, if you don't want to work with the corporate giants, DM us, here or on matrix and we'll make you an account.

After getting onto gitea your ready to begin.

Step 1

The project is split into two repositories

https://git.chapo.chat/hexbear-collective/hexbear and
https://git.chapo.chat/hexbear-collective/hexbear-frontend

clone the projects

git clone https://git.chapo.chat/hexbear-collective/hexbear.git
git clone https://git.chapo.chat/hexbear-collective/hexbear-frontend.git

OR, if you've got up ssh keys on your gitea account

git clone ssh://git@gitssh.chapo.chat:222/hexbear-collective/hexbear.git
git clone ssh://git@gitssh.chapo.chat:222/hexbear-collective/hexbear-frontend.git

Step 2

Configure your git name and email correctly so you don't accidentally Dox yourself

in the folder for each repo do...

git config user.name <Not your real name>
git config user.email <The burner email on your account>

This will let you keep your global setting for your day job if you use git regularly.

Step 3

You're Done!

Architecture overview

Getting Started

If your working via windows we recommend using Chocolatey to install these dependencies. Otherwise use your system package manager in Linux (pacman, apt, yum) or brew on MacOS

Here are some dependencies common to both the backend and frontend. Most of the time when doing work on either side you also need the other side running, so you'll probably want to install all dependencies.

Install NVM

NVM Repo

You can follow the instructions on their repo to also get the latest version of node for your OS of choice.

Install Yarn

Yarn

Yarn is the package manager we already use so it's suggested here.

Install TypeScript

yarn global add typescript

Backend Quickstart

For most backend and frontend work

Install Knex

This step is optional for if you want to run migrations/seeders through the knex cli, it's fine to skip it if you don't want to do this step
yarn global add knex

PostgreSQL

EnterpriseDB has installers for windows/osx/linux that will come with some management tools for qol. We currently use version 12.
Docker Official docker if you prefer that route, just make sure to update src/database/knexfile.ts with the correct ip address/port.
pgAdmin Cross platform GUI tool to manage postgresql databases. This comes with the EnterpriseDB installers. If you're not comfortable with using psql this is the recommended route.

Using psql or pgAdmin we want to:

  • Create a user hexbear with password hexbear
  • Create a database hexbear with owner hexbear
  • Make a schema called public if it does not exist
  • Make a schema called knex, this won't exist by default. We will store our knex migrations there so they arent affected by operations involving the main schemas.

The above matches what we use in src/database/knexfile, if you have a preferred local setup then you can adjust the knexfile. But be warned that the initial migration assumes an empty database with a user hexbear so adjust accordingly.

Migrations/Seeders

To create a migration: yarn run knex:migration-make migration_name_here
To run all pending migrations: yarn run knex:migration-run
To create a seeder file: yarn run knex:seed-make seed_name_here
To run all seeds: yarn run knex:seed-run

To handle running specific migrations or seeds, the same scripts can be used but you'll need to specify the file name.
For migrations: knex migrate:(up|down) file_name
seeds: knex seed:run --specific=file_name

Starting the Backend

  • Clone the backend repo and run yarn
  • Run yarn run knex:migration-run to build your database
  • (Optionally) run yarn run knex:seed-run to populate your database
  • Start the server with yarn run dev

Go to http://localhost:8080 to play pong or http://localhost:8080/api/v1/users to see sample data!

Frontend Quickstart

The frontend is located in the hexbear-frontend repo. Instructions for it are below....

Dependencies

All frontend dependencies are downloaded through the yarn package manager. When you first pull the code, run yarn install in the frontend folder to download these. If something isn't working after you've pulled from main, try running this command to check if any new dependencies have been added.

Starting the Frontend

Starting the frontend is dead simple. yarn run will get the frontend server going. It has hot reload, so you don't have to restart the server every time you make changes (they come into effect automatically). If all you're getting is a blank grey page, try running node generate-git-version.js to autogen the version number for the site. Also check your dev console. A lot of times I have this issue it's because the frontend isn't able to connect to the backend. If you're still stuck, pop into the hexbear-dev matrix room, we're happy to help!

Linters? Formatting?

Linting is handled by eslint, formatting is handled by prettier. It's all done when committing so you don't have to worry about remembering to format your code. Sometimes, eslint will block you from committing valid code because it caught a false positive - you can disable specific rules inline as described here.

Other Tools

IDE/Editors
VSCode - Has great TS support, autocomplete, is open source* (but MS backed), cross platform and one of the more popular editors out there
*"Code" (without the VS part) is completely open source, "VSCode" is based off of Code but is released under a Microsoft Product License

DB/Querying
Postico - OSX postgresql app. Has a slicker UI and is easier to use than pgAdmin but mainly built for querying and lacks management options
DBeaver - Cross platform, good name, probably runs better than pgAdmin

Pull requests

The basic flow to contribute goes as follows:

  1. Make a branch named feature/<name> , fix/<name> or bug/<name> etc. off the main branch of the repo.
  2. Do some work
  3. Push your branch and then submit a Pull Request to the main repo to merge into main. Try to tag your request appropriately.
    • if your work is still in progress, mark it as such.
  4. a member of the hexbear-aprovers team will review your work. Generally, at least two people should review and approve the pull request and the CI should pass
  5. Once the pull request has been approved a maintainer will merge your work.