Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add initial ARCHITECTURE document #749

Open
wants to merge 7 commits into
base: master
Choose a base branch
from
Open

Conversation

Dekkonot
Copy link
Member

A while ago, I was reading a blog post by the creator of Rust Analyzer recommending an 'ARCHITECTURE.md' document for sufficiently large projects. That blog post is here if you're curious.

While I don't think we need a lot of what they're suggesting, I think a document in the same style would be very helpful for Rojo. While it's fine for only a handful of people to know everything about the codebase, having a map of it and the mechanisms it uses would make directing new contributors significantly easier.

To that end, I've drafted an initial version of an 'ARCHITECTURE.md' document. It's incomplete, but I'm hoping that having a baseline will allow us to add to it over time and make the job less obnoxious; one person shouldn't have to write and maintain all documentation.

@Dekkonot Dekkonot added meta Issues about issue management itself. skip changelog PRs that may skip the changelog enforcement check labels Jul 27, 2023
@u-train
Copy link
Contributor

u-train commented Jul 27, 2023

So, I have a different idea on how to start the document. I think we should start with ServeSession first instead. It's the core of Rojo, since the command line interface and web API depends on ServeSession and ServeSession uses a lot of the codebase (ChangeProcessor, Vfs, RojoTree).

Bringing it up first gives the context to the rest of the codebase and why it does the things it does. For example, it's impossible to explain LiveServer (which backs serve) without explaining ServeSession and its API.

ARCHITECTURE.md Outdated Show resolved Hide resolved
ARCHITECTURE.md Outdated Show resolved Hide resolved
ARCHITECTURE.md Outdated Show resolved Hide resolved
ARCHITECTURE.md Outdated Show resolved Hide resolved

## Data Structures

Rojo has many data structures and their purpose might not be immediately clear at a glance. To alleviate this, they are documented below.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should also document the structures in the plugin, like PatchSet. It's particularly important because of how inconsistent things are with camelCase and PascalCase in our structures across the project.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We'll need to do this with Plugin and Server headers in this section due to the duplicate naming (ie: ServeSession) making the distinctions critical.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Following up
Because this doc is just meant as a high level introduction to Rojo functionality, we don't need to document the details of every plugin structure. I do think PatchSet is still very important to document though, because its the main thing the plugin interacts with during core functionality.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We have a dedicated Plugin subsection that this can go in if need be, though maybe it's worth giving the Plugin its own document?

ARCHITECTURE.md Outdated Show resolved Hide resolved
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
meta Issues about issue management itself. skip changelog PRs that may skip the changelog enforcement check
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants