Skip to content

Latest commit

 

History

History
185 lines (116 loc) · 4.55 KB

CONTRIBUTING.md

File metadata and controls

185 lines (116 loc) · 4.55 KB

🤝 Contribution Guidelines

Thank you for your interest in contributing to the Django Ultimate Advanced Guide.

This repository aims to become the global reference for advanced and enterprise-level Django concepts.
To maintain exceptional quality, every contribution must follow strict technical and editorial standards.

📌 Who Can Contribute?

This repository welcomes contributions from:

  • Senior Django developers
  • Backend engineers
  • Software architects
  • DevOps engineers
  • Researchers and educators
  • Contributors with real-world production experience

If you are learning Django, you are welcome to contribute by improving examples or documentation — but advanced technical sections require strong expertise.

🧠 What You Can Contribute

Contributions may include:

📝 Content

  • New expert-level chapters
  • Corrections or clarifications to existing content
  • Architecture diagrams (PNG, SVG, Mermaid)
  • Real-world case studies
  • Benchmarks and performance analyses

💻 Code

  • Django example apps inside each examples/ directory
  • Scripts (Python or Bash) to automate or demonstrate advanced concepts
  • Tools, utilities, and patterns for enterprise Django development
  • Tests (unit, integration, performance, async)

🛠 Fixes & Maintenance

  • Typos and grammar corrections
  • Code cleanup in example projects
  • File organization improvements
  • Enhancements to project automation (Makefile, scripts, templates)

📂 Repository Structure Requirements

Each section folder (e.g. core-internals/, orm-deep-dive/) contains:

/section-name/
README.md           ← Theory & explanations
/examples/          ← One Django mini-project per section
django_example_project/
create_app.py   ← Script to generate compliant apps

⚠ IMPORTANT

All new example apps MUST be generated using the provided script:

python examples/create_app.py my_app

This ensures consistency and maintainability across the repo.

🧩 Technical Standards

For Code Contributions:

  • Must follow PEP 8 and Django recommended style
  • Use type hints everywhere
  • Tests must accompany any technical content
  • Prefer class-based views, services, and repositories
  • Avoid business logic inside models or views
  • Example apps must remain simple, isolated, and reproducible

For Content Contributions:

  • Must be written in English (international reach)
  • Must be structured, detailed, and technically accurate
  • Include code snippets when relevant
  • Include diagrams if concept is architectural
  • Include references whenever possible

🧪 Tests

Every PR containing Django code MUST include at least:

  • pytest unit tests
  • Integration tests (if relevant)
  • Async tests for async-related topics

Run all tests using:

pytest

📝 Writing a Good Pull Request

Before submitting your PR:

  1. Sync your fork with the main branch
  2. Ensure your content is technically correct
  3. Ensure example apps run without errors
  4. Ensure docs are formatted properly
  5. Ensure tests pass

PR Format (Required):

🧠 Summary

Clear explanation of what this PR adds or fixes.

📘 Technical Details

Deep, structured explanation of the concept.

🧪 Tests / Examples

How to run them + expected output.

📎 References

(Optional) RFCs, official Django docs, academic papers.

🔄 Branching Strategy

Use the following naming conventions:

feature/<topic-name>
fix/<description>
docs/<section-name>
refactor/<topic>
tests/<topic>

Examples:

feature/orm-window-functions
docs/async-deep-dive
fix/middleware-diagram

🎯 Core Principles of This Project

Every contribution must align with the following objectives:

  • Clarity — Concepts should be explained with precision
  • Depth — Content must go beyond simple tutorials
  • Professionalism — Production-grade examples only
  • Consistency — Same structure across all sections
  • Educational Value — Aimed at architects and senior engineers

If your contribution does not significantly add clarity, depth, or value — reconsider it.

🔔 Code of Conduct

All contributors must follow the project’s
➡️ CODE_OF_CONDUCT.md
to maintain a respectful, constructive environment.

⭐ Thank You

Your contribution helps build the most advanced Django guide ever created.
Together, we are shaping a resource the entire world can learn from.

If you have questions, open an issue — we will help you get started.