Repo setup for contribution is not working

[mpizenberg]

Hi, so I said in the last gov tool meeting, I would give a try at setting up the repo as an external contributor and provide some feedback. I will be blunt, my honest feedback is that it is quite messy, and I gave up after not even managing to set up the frontend tools.

First, the contributing guideline is extremely verbose, list all constraints about bug reports, conventions, pull request workflow, versioning, and other mildly important subjects (most of time a link to a standard would suffice) but for the code contribution section, there is nothing, just a TODO.
Also, one section title reads "Merge Commit PRs and Rebase Branches on top of Main".
But everywhere else, only the "develop" branch is mentioned, which seems to be the correct one according to the default one set in the GitHub repo, not "main".

So, getting back to the root repo readme, we learn that the project is split into different parts, backend, frontend, etc.

I get into the Backend part, to check what I would need to do to set it up. There I learn that the backend is a Haskell project, and that the setup requires, nix and direnv. Unfortunately, I don’t use these. And my understanding of the dev scene is that you will find very few people willing to contribute to a Web project based on that stack. If wide open source contribution are a goal, I’d suggest basing the backend stack on more widely used platforms. There are plenty of easy to install and use indexers, such as Kupo for example, which is available via brew, docker, or statically compiled executables, and much lower-resource, so easier to run on personal laptops.

So then I tried the Frontend part.

The second instruction I was already lost. Fill .env based on env.example file. There is a typo since it’s .env.example (starting with a dot), but what should I put in these VITE configs? Nowhere I found any explanation on what to put there.

The line after, we are told to cd into govtool/frontend. But in fact, that folder does not exist, it should be govtool/govtool/frontend.

After getting there, and as instructed I tried to install the frontend dependencies:

❯ yarn install
yarn install v1.22.22
warning package-lock.json found. Your project contains lock files generated by tools other than Yarn. It is advised not to mix package managers in order to avoid resolution inconsistencies caused by unsynchronized lock files. To clear this warning, remove package-lock.json.
[1/4] 🔍  Resolving packages...
[2/4] 🚚  Fetching packages...
error [email protected]: The engine "node" is incompatible with this module. Expected version "20 || >=22". Got "18.20.4"
error Found incompatible module.
info Visit https://yarnpkg.com/en/docs/cli/install for documentation about this command.

As you can see, it’s failing. The lts/hydrogen specified in the .nvmrc is v18, so how is that possible if the minimatch@10 in the lock file depends on node >= 20 ? How do you guys manage to install the js dependencies?

Then there is a developing section. Why put versions of everything here while they should be in the package.json instead. Putting that in two places almost guaranties that one of them will get outdated.

Then we get to the pre-requisites. Why is this after the installation steps?

At this point I basically gave up trying to set it up. But out of curiosity, I still went reading the Infra readme. On this I might very well be wrong but I feel like we are bringing a flamethrower to light a candle. Is Terraform really necessary to deploy a tool that rarely has more than 100 concurrent users? Maybe the descriptive nature of the TF justifies it. This is just my 2 cents, because I’m really not a devops guys.

[bosko-m]

@mpizenberg I honestly appreciate and value this feedback, thank you!
We'll analyze it piece by piece and act on it.