Add docs about coding style/architecture and point AI agents at it #1063
Conversation
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #1063 +/- ##
=======================================
Coverage 82.09% 82.09%
=======================================
Files 53 53
Lines 7310 7310
Branches 7310 7310
=======================================
Hits 6001 6001
Misses 1019 1019
Partials 290 290 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
There was a problem hiding this comment.
Pull request overview
This pull request adds comprehensive documentation about the coding style and architecture of the MUSE2 project to help new contributors and AI agents understand the codebase. It creates a new architecture guide and configures the repository to direct AI agents to this documentation.
Changes:
- Added detailed architecture and coding style documentation covering deployment, error handling, logging, testing, example models, unit types, and file I/O
- Created AGENTS.md file to guide AI agents to the architecture documentation
- Updated VS Code settings to enable use of AGENTS.md file
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| docs/developer_guide/architecture.md | New comprehensive documentation covering MUSE2 architecture, coding style, testing practices, and development guidelines |
| AGENTS.md | New file directing AI agents to consult the architecture documentation when generating or reviewing code |
| docs/SUMMARY.md | Added the new architecture document to the documentation table of contents |
| .vscode/settings.json | Enabled VS Code to use the AGENTS.md file for AI chat features |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
tsmbland
left a comment
tsmbland
left a comment
There was a problem hiding this comment.
This is brilliant! Thanks so much for putting this together. Time will tell how useful this is for AI agents, but with some very quick testing it seems to be registering the file and taking it into consideration. In any case, this will certainly be useful as and when new people get involved with the project.
I can't think of anything I'd add off the top of my head, but I imagine we'll end up refining this as we go along.
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
alexdewar
force-pushed
the
coding-style-docs
branch
from
2527352 to
0c89e50
Compare
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
|
@Aurashk If you get a chance to take a look at this too (as the most recent MUSE2 newbie), that'd be great! No rush though. This doesn't need to be merged urgently. |
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Aurashk
left a comment
Aurashk
left a comment
There was a problem hiding this comment.
Looks helpful!
The name architecture.md throws me off a bit. If it's intended to help people get started I would probably call it architecture_quickstart.md or something.
It might be nice to include a few code excerpts/examples. For instance - to demonstrate the handling of a user-facing error vs how to handle a developer error, writing to the info log vs writing to the warn log etc.
|
|
||
| ## Input and output files | ||
|
|
||
| File formats for MUSE2 input and output files are described [in the |
There was a problem hiding this comment.
As the intended audience is new people. Might be useful in this section to highlight at the start that users provide the model definition by populating csv files with hardcoded names, with some of the files being optional (further details in the docs). And similarly the output is generated to a series a hardcoded filenames. You could also point to src/input for model inputs and src/output.rs for model outputs
|
|
||
| Note that the log level is configurable at runtime; see [user guide][logging-docs] for details. | ||
|
|
||
| ## Writing tests |
There was a problem hiding this comment.
You may want to move some of this stuff in the testing section to a new section commiting to the repository and mention about clippy and the pre-commit hooks since that's an important part of contributing. It may be useful to include a list of typical commands to run before attempting to push a remote commit e.g.
cargo test
cargo clippy
cargo clipfix
So that people aren't taken by surprise when their push is rejected
There was a problem hiding this comment.
That's a good idea, but I think it would fit more naturally here: https://energysystemsmodellinglab.github.io/MUSE2/developer_guide/coding.html
Maybe it makes sense to turn that document into more of a "here's what a developer workflow should look like" thing.
|
Thought of one more (particularly for the AI): Prefer |
Yes! Pet peeve of mine |
|
Thanks @Aurashk. All good suggestions 😄. |
Description
I've had a go at writing some docs giving an overview of the coding style/architecture used for MUSE2. Hopefully it'll be useful for new contributors to the repo as well as AI agents. The AI agents could probably benefit from more detailed instructions than I've provided (more like the prompt @tsmbland used for #1058), but for now I've created an
AGENTS.mdfile that just tells agents to look at this new document. We can add more agent-specific details as we go along.It should work with Copilot reviews as well as Copilot from VS Code and other tools (e.g. Cursor) as
AGENTS.mdis supposed to be a kind of standard.Closes #1060.
Type of change
Key checklist
$ cargo test$ cargo docFurther checks