update documentation

RELEASING.md

@@ -0,0 +1,111 @@
+# Releasing a New Version
+
+## Create Release Branch
+
+Create a new git branch off of `main` for the release.
+
+The name should follow the naming convention `release/<version>`, where `<version>` is the next incremental version number (e.g. `release/v0.1.0` for version 0.1.0).
+
+```bash
+git checkout -b release/v<version>
+```
+
+By default, only a subset of the test suite runs on PRs. Any branch named with the prefix `release/*` will trigger the full test suite to run. 
+
+## Update Documentation
+
+### Run cog
+
+```bash
+uv run --with bumpver --with cogapp --with nox cog -r <COG_FILES>
+```
+
+### Convert GitHub-Flavored Markdown to Mkdocs
+
+```bash
+uv run docs/processor.py
+```
+
+## Update CHANGELOG
+
+Ensure the [CHANGELOG](CHANGELOG.md) is up to date. If updates are needed, add them now in the release branch.
+
+## Bump Version Number
+
+Update the version number across the project using the `bumpver` tool. See [this section](#choosing-the-next-version-number) for more details about choosing the correct version number.
+
+The `pyproject.toml` in the base of the repository contains a `[tool.bumpver]` section that configures the `bumpver` tool to update the version number wherever it needs to be updated and to create a commit with the appropriate commit message.
+
+Run `bumpver` to update the version number, with the appropriate command line arguments. See the [`bumpver` documentation](https://github.com/mbarkhau/bumpver) for more details.
+
+**Note**: For any of the following commands, you can add the command line flag `--dry` to preview the changes without actually making the changes.
+
+Here are the most common commands you will need to run:
+
+```bash
+uv run --with bumpver bumpver update --patch  # for a patch release
+uv run --with bumpver bumpver update --minor  # for a minor release
+uv run --with bumpver bumpver update --major  # for a major release
+```
+
+To release a tagged version, such as a beta or release candidate, you can run:
+
+```bash
+uv run --with bumpver bumpver update --tag=beta
+# or
+uv run --with bumpver bumpver update --tag=rc
+```
+
+Running these commands on a tagged version will increment the tag appropriately, but will not increment the version number.
+
+To go from a tagged release to a full release, you can run:
+
+```bash
+uv run --with bumpver bumpver update --tag=final
+```
+
+### Choosing the Next Version Number
+
+We try our best to adhere to [Semantic Versioning](https://semver.org/), but we do not promise to follow it perfectly (and let's be honest, this is the case with a lot of projects using SemVer).
+
+In general, use your best judgement when choosing the next version number. If you are unsure, you can always ask for a second opinion from another contributor.
+
+## Update `uv.lock`
+
+```bash
+uv lock
+```
+
+## Create Release PR
+
+Create a pull request from the release branch to `main`.
+
+Once CI has passed and all the checks are green ✅, merge the pull request.
+
+## Create New GitHub Release
+
+### Using CLI
+
+```bash
+gh release create v<version> --generate-notes
+```
+
+If this is a tagged version (e.g. `alpha` or `beta`), make sure to call the create command with the `--prerelease` flag:
+
+```bash
+gh release create v0.0.0a0 --generate-notes --prerelease
+```
+
+### Using Web
+
+Draft a [new release](https://github.com/joshuadavidthomas/django-language-server/releases/new) on GitHub.
+
+Use the version number with a leading `v` as the tag name (e.g. `v0.1.0`).
+
+Allow GitHub to generate the release title and release notes, using the 'Generate release notes' button above the text box.
+
+If this is a tagged version (e.g. `alpha` or `beta`), make sure to check the 'Set as a pre-release' checkbox.
+
+## Publish to PyPI
+
+Once a GitHub release has been published, GitHub will automatically run the full test suite, including building the package against all supported OSes, Python and Django versions. Once this test suite run passes, a GitHub Actions job will publish the new version of the package to PyPI.

docs/changelog.md

@@ -0,0 +1,92 @@
+---
+title: Changelog
+---
+
+<!--
+THIS FILE IS AUTO-GENERATED
+DO NOT EDIT THIS FILE DIRECTLY
+Generated via docs/processor.py from CHANGELOG.md
+-->
+
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project attempts to adhere to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+<!--
+## [${version}]
+### Added - for new features
+### Changed - for changes in existing functionality
+### Deprecated - for soon-to-be removed features
+### Removed - for now removed features
+### Fixed - for any bug fixes
+### Security - in case of vulnerabilities
+[${version}]: https://github.com/joshuadavidthomas/django-bird/releases/tag/v${version}
+-->
+
+## [Unreleased]
+
+## [5.2.0a0]
+
+### Added
+
+- Added `html-django` as an alternative Language ID for Django templates
+- Added support for Django 5.2.
+
+### Changed
+
+- Bumped Rust toolchain from 1.83 to 1.86
+- Bumped PyO3 to 0.24.
+- **Internal**: Renamed template parsing crate to `djls-templates`
+- **Internal**: Swapped from `tower-lsp` to `tower-lsp-server` for primary LSP framework.
+
+### Removed
+
+- Dropped support for Django 5.0.
+
+## [5.1.0a2]
+
+### Added
+
+- Support for system-wide installation using `uv tool` or `pipx` with automatic Python environment detection and virtualenv discovery
+
+### Changed
+
+- Server no longer requires installation in project virtualenv, including robust Python dependency resolution using `PATH` and `site-packages` detection
+
+## [5.1.0a1]
+
+### Added
+
+- Basic Neovim plugin
+
+## [5.1.0a0]
+
+### Added
+
+- Created basic crate structure:
+    - `djls`: Main CLI interface
+    - `djls-project`: Django project introspection
+    - `djls-server`: LSP server implementation
+    - `djls-template-ast`: Template parsing
+    - `djls-worker`: Async task management
+- Initial Language Server Protocol support:
+    - Document synchronization (open, change, close)
+    - Basic diagnostics for template syntax
+    - Initial completion provider
+- Basic Django template parsing foundation and support
+- Project introspection capabilities
+- Django templatetag completion for apps in a project's `INSTALLED_APPS`
+
+### New Contributors
+
+- Josh Thomas <[email protected]> (maintainer)
+
+[unreleased]: https://github.com/joshuadavidthomas/django-language-server/compare/v5.2.0a0...HEAD
+[5.1.0a0]: https://github.com/joshuadavidthomas/django-language-server/releases/tag/v5.1.0a0
+[5.1.0a1]: https://github.com/joshuadavidthomas/django-language-server/releases/tag/v5.1.0a1
+[5.1.0a2]: https://github.com/joshuadavidthomas/django-language-server/releases/tag/v5.1.0a2
+
+[5.2.0a0]: https://github.com/joshuadavidthomas/django-language-server/releases/tag/v5.2.0a0

docs/development/index.md

@@ -0,0 +1,16 @@
+---
+title: Overview
+---
+# Development
+
+The project is written in Rust using PyO3 for Python integration. Here is a high-level overview of the project and the various crates:
+
+- Main CLI interface ([`crates/djls/`](./crates/djls/))
+- Django and Python project introspection ([`crates/djls-project/`](./crates/djls-project/))
+- LSP server implementation ([`crates/djls-server/`](./crates/djls-server/))
+- Template parsing ([`crates/djls-templates/`](./crates/djls-templates/))
+- Tokio-based background task management ([`crates/djls-worker/`](./crates/djls-worker/))
+
+Code contributions are welcome from developers of all backgrounds. Rust expertise is valuable for the LSP server and core components, but Python and Django developers should not be deterred by the Rust codebase - Django expertise is just as valuable. Understanding Django's internals and common development patterns helps inform what features would be most valuable.
+
+So far it's all been built by a [a simple country CRUD web developer](https://youtu.be/7ij_1SQqbVo?si=hwwPyBjmaOGnvPPI&t=53) learning Rust along the way - send help!

docs/development/releasing.md

@@ -0,0 +1,121 @@
+---
+title: Releasing a New Version
+---
+
+<!--
+THIS FILE IS AUTO-GENERATED
+DO NOT EDIT THIS FILE DIRECTLY
+Generated via docs/processor.py from RELEASING.md
+-->
+
+# Releasing a New Version
+
+## Create Release Branch
+
+Create a new git branch off of `main` for the release.
+
+The name should follow the naming convention `release/<version>`, where `<version>` is the next incremental version number (e.g. `release/v0.1.0` for version 0.1.0).
+
+```bash
+git checkout -b release/v<version>
+```
+
+By default, only a subset of the test suite runs on PRs. Any branch named with the prefix `release/*` will trigger the full test suite to run. 
+
+## Update Documentation
+
+### Run cog
+
+```bash
+uv run --with bumpver --with cogapp --with nox cog -r <COG_FILES>
+```
+
+### Convert GitHub-Flavored Markdown to Mkdocs
+
+```bash
+uv run docs/processor.py
+```
+
+## Update CHANGELOG
+
+Ensure the [CHANGELOG](https://github.com/joshuadavidthomas/django-language-server/blob/main/CHANGELOG.md) is up to date. If updates are needed, add them now in the release branch.
+
+## Bump Version Number
+
+Update the version number across the project using the `bumpver` tool. See [this section](#choosing-the-next-version-number) for more details about choosing the correct version number.
+
+The `pyproject.toml` in the base of the repository contains a `[tool.bumpver]` section that configures the `bumpver` tool to update the version number wherever it needs to be updated and to create a commit with the appropriate commit message.
+
+Run `bumpver` to update the version number, with the appropriate command line arguments. See the [`bumpver` documentation](https://github.com/mbarkhau/bumpver) for more details.
+
+**Note**: For any of the following commands, you can add the command line flag `--dry` to preview the changes without actually making the changes.
+
+Here are the most common commands you will need to run:
+
+```bash
+uv run --with bumpver bumpver update --patch  # for a patch release
+uv run --with bumpver bumpver update --minor  # for a minor release
+uv run --with bumpver bumpver update --major  # for a major release
+```
+
+To release a tagged version, such as a beta or release candidate, you can run:
+
+```bash
+uv run --with bumpver bumpver update --tag=beta
+# or
+uv run --with bumpver bumpver update --tag=rc
+```
+
+Running these commands on a tagged version will increment the tag appropriately, but will not increment the version number.
+
+To go from a tagged release to a full release, you can run:
+
+```bash
+uv run --with bumpver bumpver update --tag=final
+```
+
+### Choosing the Next Version Number
+
+We try our best to adhere to [Semantic Versioning](https://semver.org/), but we do not promise to follow it perfectly (and let's be honest, this is the case with a lot of projects using SemVer).
+
+In general, use your best judgement when choosing the next version number. If you are unsure, you can always ask for a second opinion from another contributor.
+
+## Update `uv.lock`
+
+```bash
+uv lock
+```
+
+## Create Release PR
+
+Create a pull request from the release branch to `main`.
+
+Once CI has passed and all the checks are green ✅, merge the pull request.
+
+## Create New GitHub Release
+
+### Using CLI
+
+```bash
+gh release create v<version> --generate-notes
+```
+
+If this is a tagged version (e.g. `alpha` or `beta`), make sure to call the create command with the `--prerelease` flag:
+
+```bash
+gh release create v0.0.0a0 --generate-notes --prerelease
+```
+
+### Using Web
+
+Draft a [new release](https://github.com/joshuadavidthomas/django-language-server/releases/new) on GitHub.
+
+Use the version number with a leading `v` as the tag name (e.g. `v0.1.0`).
+
+Allow GitHub to generate the release title and release notes, using the 'Generate release notes' button above the text box.
+
+If this is a tagged version (e.g. `alpha` or `beta`), make sure to check the 'Set as a pre-release' checkbox.
+
+## Publish to PyPI
+
+Once a GitHub release has been published, GitHub will automatically run the full test suite, including building the package against all supported OSes, Python and Django versions. Once this test suite run passes, a GitHub Actions job will publish the new version of the package to PyPI.

docs/processor.py

@@ -507,6 +507,24 @@ def main():
         ],
     )
 
+    changelog = File(
+        input_path="CHANGELOG.md",
+        output_path="docs/changelog.md",
+        processors=[
+            *common_processors,
+            add_frontmatter({"title": "Changelog"}),
+        ],
+    )
+
+    release = File(
+        input_path="RELEASING.md",
+        output_path="docs/development/releasing.md",
+        processors=[
+            *common_processors,
+            add_frontmatter({"title": "Releasing a New Version"}),
+        ],
+    )
+
     nvim = File(
         input_path="editors/nvim/README.md",
         output_path="docs/editors/neovim.md",
@@ -518,14 +536,18 @@ def main():
 
     # Process files
     readme_success = readme.process(preview=True)
+    changelog_success = changelog.process(preview=True)
+    release_success = release.process(preview=True)
     nvim_success = nvim.process(preview=True)
 
-    if readme_success and nvim_success:
+    if readme_success and changelog_success and release_success and nvim_success:
         console.print("\n[green]✨ All files processed successfully![/green]")
     else:
         console.print("\n[red]Some files failed to process:[/red]")
         for name, success in [
             ("README.md → docs/index.md", readme_success),
+            ("CHANGELOG.md → docs/changelog.md", changelog),
+            ("RELEASING.md → docs/development/releasing.md", release_success),
             ("Neovim docs → docs/editors/neovim.md", nvim_success),
         ]:
             status = "[green]✓[/green]" if success else "[red]✗[/red]"