Community Call 5/16/21: Codebase Walkthrough / Architecture Overview / Onboarding

[tangjeff0]

Summary

As new contributors and employees join Athens, we can do a better job of onboarding them to the codebase. This is a discussion to prepare for our next community call, where we can discuss the high-level architecture and also step through some specific examples of interactions.

Tools

• codeflow - video-based codebase walkthrough. can comment line-by-line
• sourcegraph - advanced code search, go to definition, ctags, find references
• Miro diagrams - already drew out some diagrams of the hairier parts of the codebase; should update and consolidate
• programmatic graph viz of codebase - not sure how useful this viz is
• Inliner: cool tool, kinda unrelated

Prompts

• What happens when we open the left-sidebar?
• What happens when we write to a block?
• What happens when Athens starts up?
• Where are all the places state is managed?
• What parts of the architecture are stable, what parts are evolving?
• What tests are written?

Next Steps

Please comment if you have any tips and tools for onboarding others to a new codebase. Also add any questions and prompts you have.

We can update this discussion or create a new one to debrief on how the call goes. Then, the evergreen material and documentation can be stored in Handbook for future reference.

[Ejipuh]

I've been learning Clojure for 8 days, and I've found myself with some basic questions. Along with those mentioned in "Prompts" above, I've been wondering:

• How is the code structured as a whole?
• What parts are related to others?
• Is there a list of dependencies and how they relate, or is this obvious within the code to those who know ClojureScript?

A little more off-topic...

• Could using a tool for code analysis like Glamorous Toolkit help in onboarding or in explaining the codebase?
  • Would this be difficult to make in Athens--a kind of "developer/curiosity mode"? (Something like Chrome's developer tools.) Would this be helpful for seeing the way the code works within the context of Athens?

[ghassanmas]

Thank you for this session,
I would just add two points if possible:

• Talk about the data model, like going over the relation/schemas,
• Do a trivial commit. Just to simulate the typical process of committing, e.g. commit message, reference issue, testing..etc

[seekanddefine]

Context: This is my first large codebase walkthrough. After attempting it myself and chatting with others, it seems setting up the dev environment can be a bigger hurdle than learning Clojure.

It would be really helpful to approach the review with an eye towards onboarding, such that the questions exposed during this process can be used to fix root causes of concern during onboarding making everything smoother for the next person. As questions expose ambiguities, how can we address them with issues and documentation?

What is the recommended process?

Could you provide an example of the smallest feature/bug to learn the process end-to-end without focusing too much on the code?