-
Notifications
You must be signed in to change notification settings - Fork 182
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
base: master
Are you sure you want to change the base?
Conversation
So, I have a different idea on how to start the document. I think we should start with 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 |
|
||
## 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. |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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?
Co-authored-by: boatbomber <zack@boatbomber.com>
Co-authored-by: boatbomber <zack@boatbomber.com>
Co-authored-by: boatbomber <zack@boatbomber.com>
Co-authored-by: boatbomber <zack@boatbomber.com> Co-authored-by: Micah <dekkonot@rocketmail.com>
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.