Skip to content

Commit 5569ab3

Browse files
MichaelHatherlyMichaelHatherly
authored
docs: add contribution guidelines and AI assistant configuration (#335)
- Add AGENTS.md with comprehensive guidance for AI coding assistants - Create CONTRIBUTING.md with AI assistance policy and PR checklist - Add Contributing section to README with AI usage guidelines - Create symlinks for Claude Code and GitHub Copilot compatibility - Document architecture, development workflow, and testing strategy - Include conventional commit guidelines and formatting requirements
1 parent b512654 commit 5569ab3

File tree

6 files changed

+117
-0
lines changed

6 files changed

+117
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../AGENTS.md

‎AGENTS.md‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
# AGENTS.md
2+
3+
Guidance for AI coding assistants working with QuartoNotebookRunner.jl.
4+
5+
## Architecture
6+
7+
QuartoNotebookRunner.jl serves as the Julia evaluation engine for Quarto's `engine: julia` directive.
8+
9+
### Main Package (`src/`)
10+
- Manages notebook parsing and worker process orchestration
11+
- `server.jl`: Core server managing notebook execution
12+
- `socket.jl`: JSON API for Quarto CLI communication
13+
- `worker.jl`: Worker process lifecycle management
14+
- `Malt.jl`: Custom vendored process management
15+
16+
### Worker Package (`src/QuartoNotebookWorker/`)
17+
- Runs in isolated Julia processes for notebook execution
18+
- All dependencies vendored in `vendor/` to avoid conflicts
19+
- `NotebookState.jl`: Manages execution state and module isolation
20+
- `render.jl`: Handles output rendering and MIME types
21+
- Extensions in `ext/` use Julia's lazy-loading mechanism via `register_package_hooks`
22+
23+
## Development Guidelines
24+
25+
### Extension Hooks & Dynamic Cells
26+
27+
Extensions register lifecycle hooks: `add_package_loading_hook!`, `add_package_refresh_hook!`, `add_post_eval_hook!`, `add_post_error_hook!`.
28+
29+
The `expand` function enables runtime cell generation, bypassing Quarto's static limitations. Extensions implement `QuartoNotebookWorker.expand(obj)` to return `Cell` vectors for iterating over data, conditional generation, and programmatic notebook construction.
30+
31+
### Testing & Version Control
32+
33+
- **Tests**: Unit tests in `test/testsets/`, integration tests in `test/testsets/integrations/`
34+
- **Before committing**: Run `just format` (see Commands section)
35+
- **Commits**: Use conventional commit style `type(scope): description`
36+
- Types: `feat`, `fix`, `docs`, `test`, `refactor`, `chore`, `style`
37+
- Example: `feat(ext): add DataFrames integration`
38+
- Always ask the user to run tests when needed
39+
40+
### Commands
41+
42+
```bash
43+
just format # format the entire codebase
44+
just changelog # generate correct PR links for changelog entries
45+
```
46+
47+
## Key Design Principles
48+
49+
- Each notebook runs in isolated Julia process with fresh module
50+
- Worker processes reused between runs for performance
51+
- Non-constant globals GC'd between runs to prevent memory leaks
52+
53+
## Environment Variables
54+
55+
- `QUARTO_JULIA`: Specify Julia binary path
56+
- `QUARTONOTEBOOKRUNNER_EXEFLAGS`: Additional Julia flags for workers
57+
- `QUARTO_ENABLE_REVISE`: Enable Revise in worker processes
58+
59+
## Socket Server Protocol
60+
61+
JSON API supports notebook execution, status queries, and worker management. See `test/testsets/socket_server/client.js` for implementation.
62+
63+
## Guidelines for AI Assistants
64+
65+
- Match surrounding code patterns
66+
- Verify worker cleanup after debugging
67+
- Use existing extensions as templates
68+
- When updating this file: use positive wording, keep instructions concise and actionable

‎CHANGELOG.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
1111

1212
- Support new requirement from `quarto` to population environment variables
1313
explicitly in the notebook process [#306].
14+
- Contributing guidelines with AI assistance policy and AGENTS.md for AI coding assistants [#335].
1415

1516
## [v0.17.3] - 2025-05-19
1617

@@ -466,3 +467,4 @@ caching is enabled. Delete this folder to clear the cache. [#259]
466467
[#304]: https://github.com/PumasAI/QuartoNotebookRunner.jl/issues/304
467468
[#305]: https://github.com/PumasAI/QuartoNotebookRunner.jl/issues/305
468469
[#306]: https://github.com/PumasAI/QuartoNotebookRunner.jl/issues/306
470+
[#335]: https://github.com/PumasAI/QuartoNotebookRunner.jl/issues/335

‎CLAUDE.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
AGENTS.md

‎CONTRIBUTING.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# Contributing to QuartoNotebookRunner
2+
3+
Thank you for contributing to QuartoNotebookRunner! Before submitting your pull request, please review these guidelines.
4+
5+
## AI Assistance Policy
6+
7+
Using AI assistants (GitHub Copilot, Claude, ChatGPT, etc.) is permitted when contributing to this project. However:
8+
9+
- **You are fully responsible for all code you submit**, whether written manually or AI-generated
10+
- Thoroughly review and test any AI-generated code before committing
11+
- Ensure AI-generated code follows the project's style and conventions
12+
- Verify that AI suggestions are appropriate for the specific context
13+
- Do not blindly accept AI suggestions without understanding them
14+
15+
Remember: AI assistants are tools to enhance productivity, not substitutes for understanding the code you're contributing.
16+
17+
## Before Submitting a PR
18+
19+
- [ ] Run `just format` to ensure code formatting
20+
- [ ] Run tests to verify your changes don't break existing functionality
21+
- [ ] Review the [development guidelines](AGENTS.md) for architecture details
22+
23+
## Development Setup
24+
25+
See the [Developer Documentation](README.md#developer-documentation) for setup instructions.
26+
27+
## Questions?
28+
29+
If you have questions about contributing, feel free to open an issue for discussion.

‎README.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,22 @@
2424
> #### [Project-wide engine](https://github.com/quarto-dev/quarto-cli/issues/3157)
2525
> If you are working with [Quarto Projects](https://quarto.org/docs/projects/quarto-projects.html), be aware that Quarto is failing to set the project-wide engine given in the `_quarto.yml` project file. A simple workaround is to set the Julia engine in each Quarto Markdown file of your project.
2626
27+
## Contributing
28+
29+
We welcome contributions to QuartoNotebookRunner! Please note:
30+
31+
### AI Assistance Policy
32+
33+
Using AI assistants (GitHub Copilot, Claude, ChatGPT, etc.) is permitted when contributing to this project. However:
34+
35+
- **You are fully responsible for all code you submit**, whether written manually or AI-generated
36+
- Thoroughly review and test any AI-generated code before committing
37+
- Ensure AI-generated code follows the project's style and conventions
38+
- Verify that AI suggestions are appropriate for the specific context
39+
- Do not blindly accept AI suggestions without understanding them
40+
41+
Remember: AI assistants are tools to enhance productivity, not substitutes for understanding the code you're contributing.
42+
2743
## Developer Documentation
2844

2945
This Julia package can run [Quarto](https://quarto.org) notebooks containing Julia code and save the

0 commit comments

Comments
 (0)