worldbrain / worldbrain-engineering Goto Github PK

• lowers bus factor
  • only Oliver is familiar with this procedure currently
• AFAIK yet to be documented in anyway

I'm working to document where we want to be moving to with the Storybook library, how we use styled-components, how we want to move towards consistency with icons, colours, type.

We will have the details of the designs inside the documentation of story book but this documentation here will outline our plan, packages, processes and current state.

Currently the documentation addon to Storybook breaks with our setup (typescript thing probably).

It seems we never merged this PR:
WorldBrain/Memex#786

In it, I've documented some basics top facilitate good coding practices, including writing understandable and maintainable code, TDD tips and principles. Let's take what's there and organize it in a nice way.

• document all keys in use
  • this was attempted in the past, although it's bound to be out-of-date: https://github.com/WorldBrain/Memex/blob/master/docs/Local-Storage-Keys.md
    - perhaps this can be documented in the code if we design a nice typed + JSDoc system to manage all interactions with local storage
• document the differences between the browser.storage.local Web Ext API and localStorage Web API
  • We're using both of these for, what seems to be, the same purpose. Perhaps we need to revisit this and ensure we're all on the same page with the two APIs. At least supply some guidelines.
• we also have a few different ways we're interacting with the relevant APIs. Some usages are directly using the APIs, others are using our own wrappers (like this: https://github.com/WorldBrain/Memex/blob/3998d34589694367e1da67d97734eb4bf0454d6a/src/util/storage.ts)

Two years ago, we agreed to rebase feature branches on develop before merging. There are advantages and disadvantages to both this approach, and merging develop into feature branches before merging. Let's collect those, reach a clear agreement on why we do what, and document that.

We're using several tools to communicate from ideation of a task to the final implementation: Slack/Zoom, Notion and GitHub. Let's make this more explicit, so we can more easily discover ways to streamline the process and communicate it to contributors/followers.

One thing to still flesh out is the technical preparation of a task starts in a GitHub issue, and then when providing feedback on the implementation, the communication moves to a PR. Where to make this move from issue to PR is not always clear.

Analytics work is nearly done: WorldBrain/Memex#976

There will be lots of times in the future where we want to ensure some new (or existing) event is tracked.
Currently the analytics class instance can just be imported directly and used as-is. This is mainly to make things simple for really old parts of the codebase that still are yet to be set up nicely so that we can pass down dependencies like this - to post-pone the refactoring that will be needed.

To discourage any new uses like this it'd be nice to get some guidelines and examples on the recommended way to track an event from different parts of the codebase.

We discussed this on slack a few years back then resulted in adding the guidelines to go with kebab-case for all files.
https://github.com/WorldBrain/Memex/blob/3b9bfec6a4c2a316cfcf3549c8808f50fc7d245f/GETTING-STARTED.md#L183-L194
We could also keep CamelCase naming for modules that export a react comp, but perhaps it's simpler having a rule consistent across all types of modules. Doesn't really matter as long as we're all onboard.

We have the problem, both in the codebase and in our heads, that we have multiple names for different features or parts of the ext+app. Maybe it would be cool to have a little glossary with the terms we want to stick with and try to make any new changes adhere to that.

Some examples:

• overview, dashboard
• lists, collections, custom lists
• annotations, comments, body, notes
• highlighter, tooltip, content tooltip
• toolbar, ribbon
• bookmark, star

A few years back we adopted the Gitflow branching model, and since then we've discussed and added further rules to our branching model such as updating minor or patch version, depending on branch type (hotfix vs release), and having certain CI checks autorun for certain branches.

There still seems to be a fair amount of confusion about how we do things with git, and I've discovered recently we often do things like build releases before CI checks pass and fork hotfix branches from develop. I feel these violations come from uncertainty about the whole process and differences in understanding among the team.

Having some simple instructions that are easy to follow and difficult to mess-up should help us avoid making these mistakes. We already have the CD pipeline instructions doc for the Memex Go repo, which is essentially a description of how the branching model works there:
https://www.notion.so/worldbrain/CD-Pipeline-instructions-2050caf8823948f6beb296129224f27a
I find these easy to follow, but that's probably because I wrote them. It would be good to expand on these for the Memex ext repo and get feedback from others on their ease-of-instruction and iterate

The "automated" CD pipeline still requires a minimal amount of manual steps that can be easily messed up, hence why we have an instructions doc:
https://www.notion.so/worldbrain/CD-Pipeline-instructions-2050caf8823948f6beb296129224f27a

Things we don't directly want to compile into code, or should be configurable at build time, are passed in as environment variables. This is handled in build/env.js and there's a plugin which gets variables from the root .env file.

To document:

• What things are controlled here?
• What am I going to need in my day-to-day development?
• Security-related concerns to not store keys in public

• yet to be documented
• in particular, accessing and setting up of our shared iOS certificates and profiles is a bit of a pain, and has proved troublesome enough when trying to onboard Oliver and Felix
  • I personally have some uncertainties about this whole procedure that I'd like to clear up too