diff --git a/.gitignore b/.gitignore index f01a2e21..b3e37348 100644 --- a/.gitignore +++ b/.gitignore @@ -435,3 +435,14 @@ dist # GeoLite city database */GeoLite2-City/* + + +# START Ruler Generated Files +*.bak +.github/copilot-instructions.md +.github/copilot-instructions.md.bak +.junie/guidelines.md +.junie/guidelines.md.bak +.vscode/mcp.json +.vscode/mcp.json.bak +# END Ruler Generated Files diff --git a/.ruler/backend.md b/.ruler/backend.md new file mode 100644 index 00000000..e2e2fc35 --- /dev/null +++ b/.ruler/backend.md @@ -0,0 +1,62 @@ +# AI Agent Instructions for backend/ + +All the following instructions must be followed when writing code in the ./backend/ directory. +This includes all Python code, tests, and any other files related to the backend project. + +## Coding Standards + +- Use Python 3.14 and Django 5.2 conventions. +- Always follow PEP8 and Python best practices for style and structure with a line length of 120. +- Name variables, functions, and classes descriptively and consistently. +- Write modular code: split logic into reusable functions and classes. +- Add concise docstrings to all public functions and classes. +- Don't use hardcoded strings, if possible. + If a function exists to generate that string, use it. + If the string is a constant, define it in its (or another appropriate) module. +- Never use `__future__` imports. +- Use type hints for all arguments and return values. +- Use type annotations for all variables, and functions. +- When having to run code, use uv to run the project and always use the `--active` flag: `uv run --active`. +- The code is formatted using `ruff` exclusively. The most used command to run is: + `ruff format . && ruff check --select I --fix ./ && ruff check --fix ./` + +## Template Standards + +- Use Django's template language for all HTML templates. +- Use Tailwind CSS 4 for styling, and ensure it is properly integrated with Django templates. +- Use Alpine.js 3 for any necessary JavaScript interactivity in templates. +- Follow best practices for template structure and organization. +- Use template inheritance to avoid duplication. +- Name templates descriptively and consistently. +- Avoid logic in templates; keep it in views or template tags. + +## Testing Requirements + +- Store tests in `tests.py` or a `tests/` directory within each app. +- Use Django's `TestCase` for all unit and integration tests. +- Write tests for every new feature, model, and view. +- Ensure tests are independent and do not rely on external state. +- Name test methods clearly and assert expected results. + +## Dependency Management + +- Add dependencies using uv: `uv pip install `. +- Let uv update `pyproject.toml` and `uv.lock` automatically. +- Never manually edit `uv.lock`. + +## Django Project Practices + +- Register new models in `admin.py` for admin access. +- Create and apply migrations for model changes. +- Keep Django settings modular and environment-specific in `settings/`. + +## Commit and Workflow + +- Ensure code is formatted and linted before commit. +- Include tests for new features and bug fixes. +- Write clear commit messages describing changes. + +## Summary + +Follow these instructions to ensure code quality, maintainability, and reliability in the backend project. +All code, tests, formatting, and dependencies must comply with these rules. diff --git a/.ruler/ruler.toml b/.ruler/ruler.toml new file mode 100644 index 00000000..b77ada37 --- /dev/null +++ b/.ruler/ruler.toml @@ -0,0 +1,50 @@ +# Ruler Configuration File +# See https://ai.intellectronica.net/ruler for documentation. + +# To specify which agents are active by default when --agents is not used, +# uncomment and populate the following line. If omitted, all agents are active. +default_agents = ["copilot", "junie"] + +# --- Agent Specific Configurations --- +# You can enable/disable agents and override their default output paths here. +# Use lowercase agent identifiers: amp, copilot, claude, codex, cursor, windsurf, cline, aider, kilocode + +[agents.copilot] +enabled = true +output_path = ".github/copilot-instructions.md" + +# [agents.claude] +# enabled = true +# output_path = "CLAUDE.md" + +# [agents.codex] +# enabled = true +# output_path = "AGENTS.md" + +# [agents.cursor] +# enabled = true +# output_path = ".cursor/rules/ruler_cursor_instructions.mdc" + +# [agents.windsurf] +# enabled = true +# output_path = ".windsurf/rules/ruler_windsurf_instructions.md" + +# [agents.cline] +# enabled = true +# output_path = ".clinerules" + +# [agents.aider] +# enabled = true +# output_path_instructions = "ruler_aider_instructions.md" +# output_path_config = ".aider.conf.yml" + +# [agents.firebase] +# enabled = true +# output_path = ".idx/airules.md" + +# [agents.gemini-cli] +# enabled = true + +# [agents.kilocode] +# enabled = true +# output_path = ".kilocode/rules/ruler_kilocode_instructions.md" diff --git a/README.md b/README.md index 3b24638f..7b2b42bc 100644 --- a/README.md +++ b/README.md @@ -110,6 +110,50 @@ If you managed to find a solution, please open a PR with the changes. 3. Run `make run` to start the containers with an PostgreSQL database 4. Open http://localhost:8080 in your browser +### Managing Coding Assistants' instructions + +The instructions for the coding assistants are stored in the `.ruler/` directory. +Each file corresponds to a specific part of the codebase and contains instructions for the coding assistants on how to +write code, tests, and manage dependencies for that part of the codebase. + +More information can be found in the [ruler.toml](.ruler/ruler.toml) file and in +the [GitHub repository](https://github.com/intellectronica/ruler) of the project. + +#### Updating the instructions + +If you want to update the instructions for the coding assistants, please update the corresponding file in the `.ruler/` +directory and make a pull request with the changes. + +#### Installing Ruler + +Having NPM installed, run the following command to install Ruler globally: + +``` +npm install -g @intellectronica/ruler +``` + +or with NPX: + +``` +npx @intellectronica/ruler apply +``` + +#### Generating the instructions for the coding assistants + +1. Go to the root of the project +2. Run `ruler apply` to generate the instructions for the coding assistants + +#### Adding new Coding Assistants + +You can find the enabled coding assistants in the `ruler.toml` file. +To add a new coding assistant, edit the `ruler.toml` file +and add a new agent to the `default_agents` list. +Please check the Ruler docs if there are any agent-specific configurations that need to be added. + +1. Uncomment the corresponding section in the `ruler.toml` file +2. Run `ruler apply` to generate the instructions for the coding assistants and `.gitignore` changes +3. Make a pull request with the changes. + ## Creating a new release The production deployment is done through a CI/CD pipeline using GitHub Actions.