docs: contributing update #11
Conversation
📝 WalkthroughWalkthroughAdds CONTRIBUTING.md, a comprehensive contributor guide for the Deepnote Toolkit. The document outlines prerequisites (Python, Java, Docker, Git), codebase structure, development setup options (mise-recommended or manual), dependency management, testing workflows, code quality standards, pull request procedures, release processes, and support channels. No public API changes. Pre-merge checks❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
Comment |
|
📦 Python package built successfully!
|
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #11 +/- ##
=======================================
Coverage 76.60% 76.60%
=======================================
Files 99 99
Lines 5476 5476
Branches 748 748
=======================================
Hits 4195 4195
Misses 1281 1281 ☔ View full report in Codecov by Sentry. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
📜 Review details
Configuration used: CodeRabbit UI
Review profile: ASSERTIVE
Plan: Pro
Disabled knowledge base sources:
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (1)
CONTRIBUTING.md(1 hunks)
🧰 Additional context used
🪛 markdownlint-cli2 (0.18.1)
CONTRIBUTING.md
44-44: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
61-61: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
66-66: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
71-71: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
76-76: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
81-81: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
86-86: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
96-96: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
103-103: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
138-138: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
146-146: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
199-199: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
208-208: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
213-213: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
302-302: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
329-329: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
339-339: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
344-344: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
350-350: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (8)
- GitHub Check: Test - Python 3.10
- GitHub Check: Test - Python 3.11
- GitHub Check: Typecheck - 3.11
- GitHub Check: Typecheck - 3.12
- GitHub Check: Build and push artifacts for Python 3.11
- GitHub Check: Build and push artifacts for Python 3.12
- GitHub Check: Build and push artifacts for Python 3.10
- GitHub Check: Build and push artifacts for Python 3.9
🔇 Additional comments (10)
CONTRIBUTING.md (10)
38-49: LGTM — mise setup option.Clear, minimal setup path with link to official docs. Good UX for users new to the toolkit.
51-90: LGTM — manual setup instructions.Well-documented fallback with platform-specific Java installation steps. Good coverage of the Poe Poetry addon and pre-commit setup.
91-105: LGTM — troubleshooting section.Practical solutions for common OpenSSL and FreeTDS issues. Helpful for users hitting these pain points.
109-132: LGTM — CLI and security guidance.Clear examples and appropriate security warnings about unauthenticated Jupyter in shared environments.
169-187: LGTM — review app and local container usage.Practical workflows for testing changes in Deepnote projects and using local containers.
219-280: LGTM — comprehensive testing section.Good coverage of mise, nox, and Docker-based testing with clear examples for each approach and different test types.
282-289: LGTM — Docker environment explanations.Clear purpose and use case for each dockerfile (builder, test, jupyter-for-local).
291-322: LGTM — code quality and style guidelines.Practical pre-commit setup and clear PEP 8 alignment with emphasis on type hints and docstrings.
325-381: LGTM — PR workflow and checklist.Conventional commit format with clear examples, practical PR checklist including security reminder.
382-414: LGTM — release process and automation.Clear workflow distinguishing staging vs production approvals and emphasizing staging validation before production merge.
| # Contributing to Deepnote Toolkit | ||
|
|
||
| Thank you for your interest in contributing to Deepnote Toolkit! This guide will help you get started with development, testing, and submitting changes. | ||
|
|
||
| ## Table of contents | ||
|
|
||
| - [Getting started](#getting-started) | ||
| - [Development setup](#development-setup) | ||
| - [Development workflow](#development-workflow) | ||
| - [Testing](#testing) | ||
| - [Code quality](#code-quality) | ||
| - [Submitting changes](#submitting-changes) | ||
| - [Release process](#release-process) | ||
|
|
||
| ## Getting started | ||
|
|
||
| ### Prerequisites | ||
|
|
||
| Before you begin, ensure you have: | ||
|
|
||
| - Python 3.10 or higher | ||
| - Java 11 (required for PySpark tests) | ||
| - Docker (for containerized testing) | ||
| - Git | ||
|
|
||
| ### Understanding the codebase | ||
|
|
||
| The Deepnote Toolkit is a Python package that runs in user environments operated by Deepnote. It consists of two main bundle types: | ||
|
|
||
| 1. **Kernel Bundle**: Libraries available to user code execution (pandas, numpy, etc.) | ||
| 2. **Server Bundle**: Dependencies for running infrastructure services (Jupyter, Streamlit, LSP) | ||
|
|
||
| **Security Note**: This code is distributed to user context and treated as a public repository. Never include secrets in the codebase. | ||
|
|
||
| ## Development setup | ||
|
|
||
| ### Option 1: Using mise (recommended) | ||
|
|
||
| [mise](https://mise.jdx.dev/) automatically manages Python, Java, and other tool versions: | ||
|
|
||
| 1. **Install mise**: Follow the [Getting Started guide](https://mise.jdx.dev/getting-started.html) | ||
|
|
||
| 2. **Run setup**: | ||
| ```bash | ||
| mise install # Installs Python 3.12 and Java 11 | ||
| mise run setup # Installs dependencies and pre-commit hooks | ||
| ``` | ||
|
|
||
| That's it! You're ready to develop. | ||
|
|
||
| ### Option 2: Manual setup | ||
|
|
||
| 1. **Install Poetry**: Follow the [official installation guide](https://python-poetry.org/docs/#installation) | ||
|
|
||
| 2. **Install Java 11** (required for PySpark tests): | ||
| - macOS: `brew install openjdk@11` | ||
| - Ubuntu/Debian: `sudo apt-get install openjdk-11-jdk` | ||
| - RHEL/Fedora: `sudo dnf install java-11-openjdk-devel` | ||
|
|
||
| 3. **Set up virtual environment**: | ||
| ```bash | ||
| poetry env use 3.10 | ||
| ``` | ||
|
|
||
| 4. **Verify environment**: | ||
| ```bash | ||
| poetry env info | ||
| ``` | ||
|
|
||
| 5. **Install dependencies**: | ||
| ```bash | ||
| poetry install | ||
| ``` | ||
|
|
||
| 6. **Install Poe Poetry addon**: | ||
| ```bash | ||
| poetry self add 'poethepoet[poetry_plugin]' | ||
| ``` | ||
|
|
||
| 7. **Install pre-commit hooks**: | ||
| ```bash | ||
| poetry poe setup-hooks | ||
| ``` | ||
|
|
||
| 8. **Verify installation**: | ||
| ```bash | ||
| poetry poe lint | ||
| poetry poe format | ||
| ``` | ||
|
|
||
| ### Troubleshooting setup | ||
|
|
||
| **Issue**: `poetry install` fails with `library 'ssl' not found` | ||
|
|
||
| **Solution**: | ||
| ```bash | ||
| env LDFLAGS="-I/opt/homebrew/opt/openssl/include -L/opt/homebrew/opt/openssl/lib" poetry install | ||
| ``` | ||
|
|
||
| **Issue**: `poetry install` fails installing `pymssql` | ||
|
|
||
| **Solution**: Install `freetds` via homebrew: | ||
| ```bash | ||
| brew install freetds | ||
| ``` | ||
|
|
||
| ## Development workflow | ||
|
|
||
| ### Running the CLI | ||
|
|
||
| The toolkit includes a pip-native CLI for local development: | ||
|
|
||
| ```bash | ||
| # Install with server components | ||
| poetry install --with server | ||
|
|
||
| # View available commands | ||
| poetry run deepnote-toolkit --help | ||
|
|
||
| # Start Jupyter server (default port 8888) | ||
| poetry run deepnote-toolkit server | ||
|
|
||
| # Start with custom configuration | ||
| poetry run deepnote-toolkit server --jupyter-port 9000 | ||
|
|
||
| # View/modify configuration | ||
| poetry run deepnote-toolkit config show | ||
| poetry run deepnote-toolkit config set server.jupyter_port 9000 | ||
| ``` | ||
|
|
||
| **Security Note**: The CLI will warn if Jupyter runs without authentication. For local development only. Set `DEEPNOTE_JUPYTER_TOKEN` for shared environments. | ||
|
|
||
| ### Local development with Docker | ||
|
|
||
| For developing against a local copy of the toolkit: | ||
|
|
||
| 1. **Build the Docker image**: | ||
| ```bash | ||
| docker build \ | ||
| --build-arg "FROM_PYTHON_TAG=3.11" \ | ||
| -t deepnote/deepnote-toolkit-local-hotreload \ | ||
| -f ./dockerfiles/jupyter-for-local-hotreload/Dockerfile . | ||
| ``` | ||
|
|
||
| 2. **Start the container**: | ||
| ```bash | ||
| docker run \ | ||
| -v "$(pwd)":/deepnote-toolkit \ | ||
| -v /tmp/deepnote-mounts:/deepnote-mounts:shared \ | ||
| -p 8888:8888 \ | ||
| -p 2087:2087 \ | ||
| -p 8051:8051 \ | ||
| -w /deepnote-toolkit \ | ||
| --add-host=localstack.dev.deepnote.org:host-gateway \ | ||
| --rm \ | ||
| --name deepnote-toolkit-local-hotreload-container \ | ||
| deepnote/deepnote-toolkit-local-hotreload | ||
| ``` | ||
|
|
||
| **Optional environment variables**: | ||
| - `-e WITH_SERVER_LOGS=1` - Include server logs in output | ||
| - `-e DEEPNOTE_PROJECT_ID=<project-id>` - Enable features requiring project ID | ||
|
|
||
| 3. **Hot reload behavior**: | ||
| - **Kernel code changes**: Restart kernel from Deepnote's UI | ||
| - **Jupyter startup code changes**: Restart container | ||
| - **Dependency changes**: Rebuild image | ||
|
|
||
| ### Using in Deepnote projects | ||
|
|
||
| When you push a commit, a new version of `deepnote/jupyter-for-local` is built with your commit hash. Use it in projects by updating `common.yml`: | ||
|
|
||
| ```yaml | ||
| jupyter: | ||
| image: "deepnote/jupyter-for-local:SHORTENED_COMMIT_SHA" | ||
| ``` | ||
|
|
||
| To use your local container, modify `common.yml`: | ||
|
|
||
| ```yml | ||
| jupyter: | ||
| image: 'screwdrivercd/noop-container' | ||
|
|
||
| executor: | ||
| environment: | ||
| JUPYTER_HOST: host.docker.internal | ||
| ``` | ||
|
|
||
| ### Review apps | ||
|
|
||
| Each PR automatically creates a review app for testing: | ||
|
|
||
| - Access it via GitHub checks | ||
| - Monitor logs in Grafana: `{pod="p-PROJECT_ID", container="notebook"}` | ||
|
|
||
| ### Adding dependencies | ||
|
|
||
| **Kernel dependencies** (available in notebooks): | ||
| ```bash | ||
| # Add a package | ||
| poetry add pandas | ||
|
|
||
| # Add with specific version | ||
| poetry add "pandas>=2.0.0" | ||
| ``` | ||
|
|
||
| **Development dependencies**: | ||
| ```bash | ||
| poetry add --group dev pytest | ||
| ``` | ||
|
|
||
| **After adding dependencies**, always run tests: | ||
| ```bash | ||
| ./bin/test-local | ||
| ``` | ||
|
|
||
| Dependencies are added to `[tool.poetry.dependencies]` in `pyproject.toml`. | ||
|
|
||
| ## Testing | ||
|
|
||
| Tests run against all supported Python versions using nox in Docker for reproducible environments. | ||
|
|
||
| ### Test coverage | ||
|
|
||
| - Unit tests for core functionality | ||
| - Integration tests for bundle installation | ||
| - Server startup tests | ||
| - Environment variable handling | ||
|
|
||
| ### Local testing | ||
|
|
||
| #### Using mise (recommended) | ||
|
|
||
| ```bash | ||
| # Run unit tests (no coverage by default) | ||
| mise run test | ||
|
|
||
| # Run unit tests with coverage | ||
| mise run test:coverage | ||
|
|
||
| # Run tests quickly without nox/coverage overhead | ||
| mise run test:quick tests/unit/test_file.py | ||
| mise run test:quick tests/unit/test_file.py::TestClass::test_method -v | ||
|
|
||
| # Pass custom arguments (including --coverage) | ||
| mise run test -- --coverage tests/unit/test_file.py | ||
| ``` | ||
|
|
||
| #### Using nox directly | ||
|
|
||
| ```bash | ||
| # Run unit tests without coverage | ||
| poetry run nox -s unit | ||
|
|
||
| # Run unit tests with coverage | ||
| poetry run nox -s unit -- --coverage | ||
|
|
||
| # Run specific test file | ||
| poetry run nox -s unit -- tests/unit/test_file.py | ||
| ``` | ||
|
|
||
| #### Using Docker | ||
|
|
||
| ```bash | ||
| # Run unit tests | ||
| TEST_TYPE="unit" TOOLKIT_VERSION="local-build" ./bin/test | ||
|
|
||
| # Run integration tests | ||
| TEST_TYPE="integration" TOOLKIT_VERSION="local-build" TOOLKIT_INDEX_URL="http://localhost:8000" ./bin/test | ||
|
|
||
| # Run both unit and integration tests | ||
| ./bin/test-local | ||
|
|
||
| # Run specific file | ||
| ./bin/test-local tests/unit/test_file.py | ||
|
|
||
| # Run specific test | ||
| ./bin/test-local tests/unit/test_file.py::TestClass::test_method | ||
| ``` | ||
|
|
||
| ### Docker test environments | ||
|
|
||
| We use Docker to ensure reproducible environments due to Jupyter libraries' binary dependencies: | ||
|
|
||
| - **`builder.Dockerfile`**: Creates Python package bundles for different versions (3.9-3.12), generates kernel and server bundles, and packages the toolkit for distribution using Poetry. | ||
|
|
||
| - **`test.Dockerfile`**: Provides consistent test environment for running unit and integration tests across Python versions using nox. Used both locally and in CI/CD pipeline. | ||
|
|
||
| - **`jupyter-for-local.Dockerfile`**: Creates development environment with Jupyter integration, used for local development from docker-compose used in main monorepo. | ||
|
|
||
| ## Code quality | ||
|
|
||
| ### Pre-commit hooks | ||
|
|
||
| Pre-commit hooks automatically run on every commit to ensure code quality: | ||
|
|
||
| - Code formatting (black, isort) | ||
| - Linting (flake8, mypy) | ||
| - Security checks (semgrep) | ||
|
|
||
| Install hooks during setup: | ||
| ```bash | ||
| poetry poe setup-hooks | ||
| ``` | ||
|
|
||
| ### Manual code quality checks | ||
|
|
||
| ```bash | ||
| # Run linting | ||
| poetry poe lint | ||
|
|
||
| # Run formatting | ||
| poetry poe format | ||
| ``` | ||
|
|
||
| ### Code style guidelines | ||
|
|
||
| - Follow PEP 8 style guidelines | ||
| - Use type hints for function signatures | ||
| - Write docstrings for public APIs | ||
| - Keep functions focused and single-purpose | ||
| - Add comments for complex logic | ||
|
|
||
| ## Submitting changes | ||
|
|
||
| ### Pull request process | ||
|
|
||
| 1. **Create a feature branch**: | ||
| ```bash | ||
| git checkout -b feature/your-feature-name | ||
| ``` | ||
|
|
||
| 2. **Make your changes**: | ||
| - Write code following style guidelines | ||
| - Add tests for new functionality | ||
| - Update documentation as needed | ||
|
|
||
| 3. **Run tests locally**: | ||
| ```bash | ||
| ./bin/test-local | ||
| ``` | ||
|
|
||
| 4. **Commit your changes**: | ||
| ```bash | ||
| git add . | ||
| git commit -m "feat: add your feature description" | ||
| ``` | ||
|
|
||
| 5. **Push to your fork**: | ||
| ```bash | ||
| git push origin feature/your-feature-name | ||
| ``` | ||
|
|
||
| 6. **Create a Pull Request**: | ||
| - Provide a clear description of changes | ||
| - Reference any related issues | ||
| - Ensure CI checks pass | ||
| - Request review from maintainers | ||
|
|
||
| ### Commit message guidelines | ||
|
|
||
| Follow conventional commit format: | ||
|
|
||
| - `feat:` - New feature | ||
| - `fix:` - Bug fix | ||
| - `docs:` - Documentation changes | ||
| - `test:` - Test changes | ||
| - `refactor:` - Code refactoring | ||
| - `chore:` - Maintenance tasks | ||
|
|
||
| Example: `feat: add SQL query caching support` | ||
|
|
||
| ### Pull request checklist | ||
|
|
||
| - [ ] Tests pass locally | ||
| - [ ] Code follows style guidelines | ||
| - [ ] Documentation updated | ||
| - [ ] Commit messages are clear | ||
| - [ ] No secrets or sensitive data included | ||
| - [ ] Review app tested (if applicable) | ||
|
|
||
| ## Release process | ||
|
|
||
| ### Production releases | ||
|
|
||
| To release a new version to production: | ||
|
|
||
| 1. **Merge to main**: Merge your changes to the main branch. This automatically triggers: | ||
| - GitHub Actions workflow | ||
| - Test suite execution | ||
| - Staging deployment | ||
|
|
||
| 2. **Create GitHub Release**: Trigger a new [GitHub Release](https://github.com/deepnote/deepnote-toolkit/releases) in the GitHub UI. | ||
|
|
||
| 3. **Monitor deployment**: Check [GitHub Actions workflows](https://github.com/deepnote/deepnote-toolkit/actions) for successful production deployment. | ||
|
|
||
| ### Automated PR creation | ||
|
|
||
| The production release pipeline automatically creates two PRs: | ||
|
|
||
| - **Staging PR**: Updates staging values and is auto-merged | ||
| - **Production PR**: Updates production values and requires manual approval | ||
|
|
||
| **Important**: Always test changes in the staging environment before approving and merging the production PR. | ||
|
|
||
| ### Release checklist | ||
|
|
||
| - [ ] All tests pass in CI | ||
| - [ ] Staging deployment successful | ||
| - [ ] Changes tested in staging environment | ||
| - [ ] Documentation updated | ||
| - [ ] Changelog updated (if applicable) | ||
| - [ ] Production PR reviewed and approved | ||
|
|
||
| ## Getting help | ||
|
|
||
| - **Issues**: Report bugs or request features via [GitHub Issues](https://github.com/deepnote/deepnote-toolkit/issues) | ||
| - **Discussions**: Ask questions in GitHub Discussions | ||
| - **Documentation**: Check the [README](README.md) and inline code documentation | ||
|
|
There was a problem hiding this comment.
🧩 Analysis chain
Verify referenced scripts and dockerfiles exist.
The guide references several files that should be verified in the repository:
./bin/testand./bin/test-local(lines 214, 266, 272, 275, 278)./dockerfiles/jupyter-for-local-hotreload/Dockerfile(line 142)./dockerfiles/withbuilder.Dockerfile,test.Dockerfile,jupyter-for-local.Dockerfile(lines 285-289)README.md(line 419)
🏁 Script executed:
#!/bin/bash
# Verify referenced files exist in the repository
echo "Checking bin scripts..."
for script in bin/test bin/test-local; do
if [ -f "$script" ]; then
echo "✓ $script exists"
else
echo "✗ $script NOT FOUND"
fi
done
echo -e "\nChecking dockerfiles..."
for dockerfile in dockerfiles/jupyter-for-local-hotreload/Dockerfile dockerfiles/builder.Dockerfile dockerfiles/test.Dockerfile dockerfiles/jupyter-for-local.Dockerfile; do
if [ -f "$dockerfile" ]; then
echo "✓ $dockerfile exists"
else
echo "✗ $dockerfile NOT FOUND"
fi
done
echo -e "\nChecking documentation..."
if [ -f "README.md" ]; then
echo "✓ README.md exists"
else
echo "✗ README.md NOT FOUND"
fiLength of output: 329
🏁 Script executed:
#!/bin/bash
# Check what dockerfiles actually exist
echo "Contents of dockerfiles directory:"
find dockerfiles -type f -name "*[Dd]ockerfile*" | sort
echo ""
echo "All files in dockerfiles directory:"
find dockerfiles -type f | sortLength of output: 165
---
🏁 Script executed:
```shell
#!/bin/bash
# List all dockerfiles in the repository
find . -type f -name "*ockerfile*" | sort
Length of output: 208
Fix incorrect dockerfile paths in the Docker test environments section.
Two dockerfile references have incorrect paths:
- Line 286:
builder.Dockerfile→builder/builder.Dockerfile - Line 289:
jupyter-for-local.Dockerfile→jupyter-for-local/Dockerfile
All other referenced files exist as documented.
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
44-44: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
61-61: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
66-66: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
71-71: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
76-76: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
81-81: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
86-86: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
96-96: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
103-103: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
138-138: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
146-146: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
199-199: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
208-208: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
213-213: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
302-302: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
329-329: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
339-339: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
344-344: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
350-350: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
🤖 Prompt for AI Agents
In CONTRIBUTING.md around lines 286 to 289, the Docker test environments section
references incorrect Dockerfile paths: change the reference "builder.Dockerfile"
to "builder/builder.Dockerfile" and change "jupyter-for-local.Dockerfile" to
"jupyter-for-local/Dockerfile"; update the two lines accordingly so they point
to the actual files in the repo and verify no other occurrences of those
incorrect filenames remain.
| 1. **Install mise**: Follow the [Getting Started guide](https://mise.jdx.dev/getting-started.html) | ||
|
|
||
| 2. **Run setup**: | ||
| ```bash |
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major
Add blank lines around fenced code blocks per MD031.
All code blocks need blank lines immediately before and after per markdownlint rules. Apply this pattern systematically throughout:
-2. **Run setup**:
- ```bash
+2. **Run setup**:
+
+ ```bash
mise install # Installs Python 3.12 and Java 11
mise run setup # Installs dependencies and pre-commit hooks
- ```
+ ```
+
That's it! You're ready to develop.This pattern repeats for all code blocks at the flagged lines.
Run the following script to identify and verify all occurrences:
#!/bin/bash
# Find all fenced code blocks and check for blank lines before/after
# Count current violations
violations=$(rg -n '^\s*```' CONTRIBUTING.md | wc -l)
echo "Found $violations code block markers"
# Show context around first few violations
rg -B 1 -A 1 '^\s*```' CONTRIBUTING.md | head -30Also applies to: 61-61, 66-66, 71-71, 76-76, 81-81, 86-86, 96-96, 103-103, 138-138, 146-146, 199-199, 208-208, 213-213, 302-302, 329-329, 339-339, 344-344, 350-350
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
44-44: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
🤖 Prompt for AI Agents
In CONTRIBUTING.md around lines 44 (and additionally at lines 61, 66, 71, 76,
81, 86, 96, 103, 138, 146, 199, 208, 213, 302, 329, 339, 344, 350), fenced code
blocks lack the required blank line immediately before and/or after the ```
markers per MD031; fix by adding a single blank line above and below each fenced
code block so every opening ``` has a blank line preceding it and every closing
``` has a blank line following it, and run the provided verification script (or
markdownlint) to confirm no remaining violations.
|
|
||
| 2. **Run setup**: | ||
| ```bash | ||
| mise install # Installs Python 3.12 and Java 11 |
There was a problem hiding this comment.
🧹 Nitpick | 🔵 Trivial
Minor: Clarify Python version guidance in manual setup.
Line 45 specifies Python 3.12 (mise installs), but line 62 uses poetry env use 3.10. For clarity, either:
- Update line 62 to match:
poetry env use 3.12 - Or clarify that 3.10 is the minimum but 3.12 is recommended
Also applies to: 62-62
🤖 Prompt for AI Agents
In CONTRIBUTING.md around lines 45 and 62 there is an inconsistency: line 45
references installing Python 3.12 while line 62 instructs `poetry env use 3.10`;
update the document to be consistent by either changing line 62 to `poetry env
use 3.12` or explicitly state that Python 3.10 is the minimum and 3.12 is
recommended (and adjust the surrounding wording to reflect that choice).
|
🚀 Review App Deployment Started
|
Summary by CodeRabbit