kvalifik / how-we-work

A handbook for software development at Kvalifik

We are soon going into production! There are some important next steps, before this happens. Please read Road map

Kvalifik dk static site

Kvalifik's new website built with Gatsby and Dato CMS!

How to develop

We use npm for all development. Make sure you have the Gatsby development tool installed gatsby-cli.

npm install

The app needs an API key to Dato CMS. Acquire this API key (read-only is sufficient) and assign it to environment variable KVALIFIK_API_KEY. This should be done in your bash settings, and should not be checked into git. Check this article how to set global variables in bash

Then

npm run start

Navigate to http://localhost:8000

Refer to Gatsby's own docs for more information about the endless universe of Gatsby!

Stack

We follow the JAMStack paradigm. Read more here.

• Dato CMS (API)
• Gatsby (Javascript and markup)
• Netlify (Static file hosting)

Documentation

Modular block setup

Content management guide

Source structure

./src
├── Components
├── graphics
├── models
│   ├── blocks
│   └── page.js
├── templates
│   └── page.js
└── utils

Components are usually larger autonomous components, but also contains Components/Shared which are smaller reusable components.

templates are template components used in the build process.

models are primarily prop type schemas, but might also contain other types of models.

utils are various utility functions that are used in various places, such as within the build process or within a component.

graphics are all graphics that never change and therefore doesn't have to be loaded from the Cms.

how-we-work's Issues

Dojo: Document Cloud Functions

Already done in another PR.

Review Rune's Dojo branch and update the data source in Google Data Studio

1. 1h Review this branch:

https://github.com/Kvalifik/dojo/pull/163

2. 0.5h When it is merged to production, update the Google Data Studio Project:

https://datastudio.google.com/s/ke0xe3WYGxw

If you have more time (2h-3h):

3. Check whether the analytics/graphs all are working and makes sense

4. Inform August and Søren, so they know, that the analytics from Dojo are now live.

Note

Nikolaj has access to the Google Data Studio Project. Read more info about the cloud function in the Pull request.

GCP Billing Account best practices

Skal udspecificeres. Står det ikke i "How we setup backend ..."?

Add language tag to blogposts

BLOCKED DUE TO UPCOMING RE-DESIGN

Our blog is currently a good 50/50 mix of english and danish, please add a tag to identify language in blogposts.

How We Setup Terraform + Google Cloud Platform for Backend Projects

Hovedansvarlig: _____

Produkt:

Markdownfil i How We Work repoet med et link til Table of Contents

Idéer:

Describe every step from an empty git repository to a fully running Node backend with CI/CD, staging and production environment and terraform setup in Google Cloud Platform.

Preferably describe each step using CLI tools such that we can easily integrate into Kvalifik CLI later.

Værdi: We currently use Terraform for handling our infrastructure, but Terraform needs bootstrapping, which is quite hard. We need to standardise it, so that every project is set up the same way (and uses the same standards for project naming, billing accounts, service accounts etc.)

Work on:

https://www.notion.so/kvalifik/How-we-setup-a-new-backend-environment-for-a-project-using-Terraform-074ce597d4c54232994b343151e4e564

Write Dojo backlog items into backlog

Dojo: CI Flow of Firestore rules + functions

Review André's branch "setup ci test flow" where he has integrated firestore rules and functions unit tests into our CI flow. Test the following:

• Unit tests work locally after merging staging into the branch (this branch reorganises the unit tests).
• Unit tests (both firestore and functions) run on every new commit to a PR or to staging branch.

Before you work on Dojo

If it is the first time you work on Dojo please skim the GitHub ReadMe to learn more about the data model, units tests, functions, environments and most important flows: https://github.com/kvalifik/dojo. Test users can be found in 1pass.

Write about package managers (NPM vs Yarn)

Package management is important to get a consistent environment across platforms, so we should be consistent in the package manager that we use. Many frameworks default to using Yarn instead of NPM (like Expo for example), so we need standardization.

Change default repository access on GitHub

• Make Core Dev Team Owners. Make stakeholders owners.
• Change default repository access to none.
• Make team for praktikanter.
• Write message on #dev annoucing the change. Asking then to contact André and Nikolaj to regain access to specific repos.

Kvalifik Git flow a la Lars Kruse

Setup a project agnostic workflow with custom git commands a la Lars' 'work-on' & 'deliver' to streamline our flow

Nice to have: connect these to project specific workflows, so eg:

On Shopify, we use ThemeKit concurrently with git. Maybe "work-on" starts a branch, creates a theme, deploys the theme. Deliver, deletes the theme, merges into master.

(Sub)-Domain Overview

Opening up KvaliHack to Dojo and more

How We Use NestJS/Node.js

Hovedansvarlig: _____

Produkt:

Markdownfil i How We Work repoet med et link til Table of Contents

Idéer:

Describe the standards that we wish to enforce when using NestJS

• SOLID principles, services

• TypeORM, Postgres

• How we migrate the database

• Terraform

• CLI

• How we test

• File naming policies.

• Links to documentation

• Links to repos that use NestJS well

• How we use Docker

• How we use docker-compose

• How we use Terraform

• How we use Google Cloud Platform

• How we handle environment variables

• How we handle authentication

• How we handle controller construction according to REST

• How we seperate environments

Værdi: We use NestJS for many of our backends, and we need to enforce standards in how we do it.

Set up template Forecast projects

To ensure all projects follow the same settings and column structure, we should make templates for each project type, that we can then duplicate for subsequent projects.

Eg:

An agile retainer project with a 'Inbox', 'Backlog', 'To do', 'In Progress', 'Runway', 'Awaiting Approval' and 'Delivered' column.

A generic project with Followers turned on, tracking in Points.

Bonus;

To further improve GitHub integration, consider marking 'Awaiting Approval' as a 'Done' column. This way, when a pull request referencing the task is closed, Forecast will move it to the nearest 'done' column (see attached).

Dojo (High): Mail to talent onTaskUpdate instead of onTaskCreate

High priority: Only send a mail to the talents when a task is updated to beeing "visible".

Background

The Task Bidding Page, https://app.dojo.dk/task-bidding, is where talents on Dojo can see new tasks from clients and offer to work on them. All tasks have a `visible` field which determines whether the task is visible to the talent on the task bidding page. Currently a task is per default not visible on creation, but a mail is still send out to talents notifying them of new tasks.

Before you work on Dojo

If it is the first time you work on Dojo please skim the GitHub ReadMe to learn more about the data model, units tests, functions, environments and most important flows: https://github.com/kvalifik/dojo. Test users can be found in 1pass.

Make cookie popup compliant på kvalifik.dk.

Consider changing to cookiebot. Talk to Søren and Nikolaj for details.

Bedre projekt/tasks management system, der taler godt sammen med GitHub.

Hovedansvarlig: Frederic

Produkt:

Behovsafklaring fra udviklere, designer, kunder og projektledere.

Forslag på mulig ny løsning, herunder 5 minutters demo.

Idéer: GitHub, ZenHub(!), Jira, GitLab(!!!).

Værdi: Vi arbejder mere struktureret og får sammenkoblet vores opgaver med den kode, vi leverer. Det skaber arbejdsglæde og overskud.

How We Use Shopify

Hovedansvarlig: _____

Produkt:

Markdownfil i How We Work repoet med et link til Table of Contents

Idéer:

Describe the standards that we wish to enforce when using Shopify

• Git integration

• Branch/Theme handling

• Styling

• Theme kit / Shopify CLI

• Skeleton Theme

• CI/CD

• Shopify Partners

Værdi: We use Shopify for all of our webshops and are very reliant on them. We need to document standards for handling of styling, JS, DevOps etc.

Implement LambdaTest screenshotting into CI/CD for Shopify

Testing Shopify theme's is very

Add 'How we use Forecast'

Implement "Track time" functionality

Add 'How we work with Shopify'

How We Use Request Libraries

Needs time allocated as of 8/2

Meetings

Create overview of all live softwareservices

We're paying almost 20k a month for software services. Sometimes we forbget an old server or to transfer the cost to the customer. Let's create a sustainable overview of the services that we have, so we can remove those we do not use and transfer the financial ownership to the right orgaizations

Fix Jekyll

I tried to make a fast Jekyll integration, but it turned out to be harder than otherwise thought. I have therefore chosen to focus on other matters.

Write about preferred request client (Axios vs Fetch vs ...)

Different projects use different clients. Let's standardise that!
Most of our projects use Axios, which I believe is fine.

Axios:
Pros: Well known, many use it, most of our projects use it, easy to use API
Cons: External dependency, a bit bloated, takes very few contributions to their repository

Fetch:
Pros: Already packaged with most environments, small
Cons: Slight differences in different environments (node vs browser)

How We Use Next.js

Hovedansvarlig: _____

Produkt:

Markdownfil i How We Work repoet med et link til Table of Contents

Idéer:

Describe why we use Next.js. Example content:

• Links to projects that use Next.js well.

• Link to React, Next documentation

• How we use Vercel

• How / when we use Redux (and when do we not)

• How we handle communication with a backend

• How we handle styling (link to TailwindCSS)

• How to setup a project using Next.js (+ terraform for Vercel) (duplicate an existing project)

• Link to TypeScript, ESlint, Prettier page (todo)

Værdi: We use Next.js for all our React projects, but we need standards for network handling, styling and linting

Setup GitHub teams for all client projects

Konverter how we work Indholdsfortegnelse til tasks/backlog items

Hovedansvarlig: Frederic

Produkt: Indholdsfortegnelse over de ting, vi gerne vil standardisere blandt udviklingsteamet. Bemærk, at vi skal have alt med. Tænkt på det som en onboarding guide til nye udviklere. Fx kunne et punkt være "Where is our code located" (hvor svaret nok er GitHub).

Foreløbig plan: Som en start vil vi gerne have bedre struktur (en standard) for, hvordan vi arbejde internt i udviklingsteamet. Med tiden kan vi udbrede og standardisere vores workflows sammen med projektledere, designere, sælgere osv.

Vi forestiller os et markdown repo på GitHub, dvs. en række markdown filer på roden og en indholdsfortegnelses-markdown-fil, der linker til dem. Når indholdsfortegnelsen er på plads (produktet af denne opgave), så kan vi uddelegere at skrive de enkelte markdown-filer. Vi mangler dog at blive enige om selve indholdet.

Værdi: Vi arbejder mere effektivt og struktureret. Det skaber også arbejdsglæde og overskud.

Services overview / Handover from Nils

Ny model/retningslinjer for tidsregistrering og allokering

Hovedansvarlig: Nikolaj

Produkt:

Behovsafklaring fra fastansatte, timelønnede, projektledere og ledelse.

Forslag på mulig ny løsning med 5 minutters demo.

Værdi: Mindre presset hverdag og øget arbejdsglæde, mens vi stadigvæk har mulighed for at udtrække de metrics, som ledelsen har behov for.

Write about our use of Result types

In many of our projects, we use something like a "Result" type for our network requests. It often looks something like this:

{
    success: true,
    ok: any
} | {
    success: false,
    err: {
        code: number,
        message: string
    }
}

This should be documented so I can be standardized

Dockerizaton of a Google Cloud Project (incl. documentation or template repo)

Work on:

https://www.notion.so/kvalifik/How-we-setup-a-new-backend-environment-for-a-project-using-Terraform-074ce597d4c54232994b343151e4e564

Adjust text scaling on Kvalifik.dk

BLOCKED DUE TO UPCOMING RE-DESIGN

Make sure that text stay in the container and is readible in all formats.

How We Use Forecast

Hovedansvarlig: _____

Produkt:

Markdownfil i How We Work repoet med et link til Table of Contents

Idéer:

Describe the standards that we wish to enforce when using Forecast

• Retainer projects vs Product projects vs Internal projects
• How we break down User Stories into tasks
• How we use the terms User Stories, Tasks, Epics
• How we use Labels
• How we use Kanban columns
  • Principles of Kanban (maybe link?)
• Built vs Validated vs Done Done
• How we name tasks/issues in Forecast/GitHub
• How we estimate user stories
• How we review user stories
• How to use Followers / How to involve clients
• How to integrate with Github
• Link to "How we track time" (notion)

Værdi: We use Forecast for all of our projects, but every single project is slightly different in the way it is managed. Let us set a standard that we can use for everyone

How We Use Github

Hovedansvarlig: _____

Produkt:

Markdownfil i How We Work repoet med et link til Table of Contents

Idéer:

Could contain the following points:

• How we use Teams
• How we use Issues & Pull Requests
• How we use commits and commit messages
• How we use branches
• How we use code reviews
• How we use the Forecast Integration
• How we setup new repositories
• How we use branch rules
• How we use 2FA / SSH keys

Links to other future pages:

How we use Github Actions

How we use Kvalifik CLI

Værdi:

New (and old) developers in Kvalifik should understand how we use Github for code, documentation, CI/CD and project management. This defines a standard for how we use git in general.

Dojo Emails are still going to spam

Last steps: Setup af DKIM så emailen er signeret af Dojo.dk og matcher afsender.

Mulige next steps: DMARK & potentielt email indhold.

My task is unclear – what do I do?

Open the item here in Forecast. In the lower left corner you'll find the person who created it. Go talk to this person for clarifications.

Dojo: Finish export to BigQuery

There is a Google Data Studio Project displaying analytics from Dojo: https://datastudio.google.com/s/rfjB8OWjPiw.

The data from dojo is exported from Firestore -> Cloud Storage Bucket -> BigQuery -> Google data Studio.

The branch "feature/big-query-export" is a month-old work in progress which currently exports from Firestore to Google Cloud Storage bucket. But the link from GC Storage -> BigQuery is missing. Thus, the following needs to be done:

1. checkout "feature/big-query-export" and merge staging into the branch
2. Review the code exporting firestore to GC storage
3. Create function for automatically exporting from the storage bucket to BigQuery
4. Update the Google Data Studio Project to use the new BigQuery data

Before you work on Dojo

If it is the first time you work on Dojo please skim the GitHub ReadMe to learn more about the data model, units tests, functions, environments and most important flows: https://github.com/kvalifik/dojo. Test users can be found in 1pass.

How We Use Result Type Interfaces

I have completed a backlog item – what now?

Great!

1. Move the backlog item to the Ready for Review column and be ready to present it (if applicable) at the next team meeting.
2. Assign yourself to the item at the top of the Team Backlog column and move it to the In Progress column. Note: You should always pick the backlog item of highest priority (i.e. at the top) even though you expect that someone else might be more qualified to solve it. This encourages everybody to acquire new skills. Remember that you are always welcome to seek help from others! 😊

Kvalifik blog & work grid can't handle black background for thumbnails

BLOCKED DUE TO UPCOMING RE-DESIGN

Add support for black bg on thumbnail, so text is visible.

Make new version of mail signature with proper line break and no left margin

New version of mail signature so it doesn't look like the screenshot in threads.

See https://www.notion.so/kvalifik/Set-up-e-mail-signature-6150a5722ca945359f7e0bde21026af7

Dojo: Code-review #163 & #164

Add multi-repo issue support to CLI

The Forecast Github integration can only sync tasks to one repository. This means that for projects involving multiple repositories, we need to alter Kvalifik-CLI's 'work-on' to fetch issues from a repository that's not the current working repo.

To achieve this, we can use the GH Cli to make authenticated API calls (https://cli.github.com/manual/gh_api).

An example would be: gh api repos/{owner}/{repo}/releases

Example for Spiritium, that has two repos, where 'spiritium-webshop' is where Forecast syncs issues:

{

"issue-repository": 'spritium-webshop'

}

Work-on should then be extended, so it checks for a 'issue-repository' in the config. When working on an issue outside of the working repository, it's impossible to link them to a pull request. Instead we'll need to mention the issue in the description and manually manage PR's and task status.

Dojo: Task Bidding Improvements

1. The Read more button should only be visible when the task description is very short.
2. As a talent, it should be shown when I have bid on a task. Note: This probably requires a larger change in the datamodel.

Background

The Task Bidding Page, https://app.dojo.dk/task-bidding, is where talents on Dojo can see new tasks from clients and offer to work on them. All tasks have a `visible` field which determines whether the task is visible to the talent on the task bidding page.

Before you work on Dojo

If it is the first time you work on Dojo please skim the GitHub ReadMe to learn more about the data model, units tests, functions, environments and most important flows: https://github.com/kvalifik/dojo. Test users can be found in 1pass.

Explore infrastructure as code

We explore the possibilities of having infrastructure as code for larger projects. This might enable us to avoid vendor lock-in and simplify the process of setting up additional environments.

Ready for review functionality

To better sync task status with GitHub, it would make sense to introduce a 'kvalifik ready-for-review' function that sets an open PR to ready for review, and subsequently moves the Forecast task to the right column.

To achieve this, we need an app with it's own Forecast API key, that we can send requests to via our CLI.
https://github.com/Forecast-it/API/blob/master/sections/workflow_columns.md#workflow-columns

Improve handling of issue names in Kvali CLI