Skip to content

Commit 57d7418

Browse files
joshuadavidthomasjoshuadavidthomas
committed
update documentation
1 parent 3fb6fa9 commit 57d7418

File tree

5 files changed

+363
-1
lines changed

5 files changed

+363
-1
lines changed

‎RELEASING.md‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
# Releasing a New Version
2+
3+
## Create Release Branch
4+
5+
Create a new git branch off of `main` for the release.
6+
7+
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).
8+
9+
```bash
10+
git checkout -b release/v<version>
11+
```
12+
13+
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.
14+
15+
## Update Documentation
16+
17+
### Run cog
18+
19+
```bash
20+
uv run --with bumpver --with cogapp --with nox cog -r <COG_FILES>
21+
```
22+
23+
### Convert GitHub-Flavored Markdown to Mkdocs
24+
25+
```bash
26+
uv run docs/processor.py
27+
```
28+
29+
## Update CHANGELOG
30+
31+
Ensure the [CHANGELOG](CHANGELOG.md) is up to date. If updates are needed, add them now in the release branch.
32+
33+
## Bump Version Number
34+
35+
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.
36+
37+
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.
38+
39+
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.
40+
41+
**Note**: For any of the following commands, you can add the command line flag `--dry` to preview the changes without actually making the changes.
42+
43+
Here are the most common commands you will need to run:
44+
45+
```bash
46+
uv run --with bumpver bumpver update --patch # for a patch release
47+
uv run --with bumpver bumpver update --minor # for a minor release
48+
uv run --with bumpver bumpver update --major # for a major release
49+
```
50+
51+
To release a tagged version, such as a beta or release candidate, you can run:
52+
53+
```bash
54+
uv run --with bumpver bumpver update --tag=beta
55+
# or
56+
uv run --with bumpver bumpver update --tag=rc
57+
```
58+
59+
Running these commands on a tagged version will increment the tag appropriately, but will not increment the version number.
60+
61+
To go from a tagged release to a full release, you can run:
62+
63+
```bash
64+
uv run --with bumpver bumpver update --tag=final
65+
```
66+
67+
### Choosing the Next Version Number
68+
69+
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).
70+
71+
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.
72+
73+
## Update `uv.lock`
74+
75+
```bash
76+
uv lock
77+
```
78+
79+
## Create Release PR
80+
81+
Create a pull request from the release branch to `main`.
82+
83+
Once CI has passed and all the checks are green ✅, merge the pull request.
84+
85+
## Create New GitHub Release
86+
87+
### Using CLI
88+
89+
```bash
90+
gh release create v<version> --generate-notes
91+
```
92+
93+
If this is a tagged version (e.g. `alpha` or `beta`), make sure to call the create command with the `--prerelease` flag:
94+
95+
```bash
96+
gh release create v0.0.0a0 --generate-notes --prerelease
97+
```
98+
99+
### Using Web
100+
101+
Draft a [new release](https://github.com/joshuadavidthomas/django-language-server/releases/new) on GitHub.
102+
103+
Use the version number with a leading `v` as the tag name (e.g. `v0.1.0`).
104+
105+
Allow GitHub to generate the release title and release notes, using the 'Generate release notes' button above the text box.
106+
107+
If this is a tagged version (e.g. `alpha` or `beta`), make sure to check the 'Set as a pre-release' checkbox.
108+
109+
## Publish to PyPI
110+
111+
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‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
---
2+
title: Changelog
3+
---
4+
5+
<!--
6+
THIS FILE IS AUTO-GENERATED
7+
DO NOT EDIT THIS FILE DIRECTLY
8+
Generated via docs/processor.py from CHANGELOG.md
9+
-->
10+
11+
# Changelog
12+
13+
All notable changes to this project will be documented in this file.
14+
15+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
16+
and this project attempts to adhere to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
17+
18+
<!--
19+
## [${version}]
20+
### Added - for new features
21+
### Changed - for changes in existing functionality
22+
### Deprecated - for soon-to-be removed features
23+
### Removed - for now removed features
24+
### Fixed - for any bug fixes
25+
### Security - in case of vulnerabilities
26+
[${version}]: https://github.com/joshuadavidthomas/django-bird/releases/tag/v${version}
27+
-->
28+
29+
## [Unreleased]
30+
31+
## [5.2.0a0]
32+
33+
### Added
34+
35+
- Added `html-django` as an alternative Language ID for Django templates
36+
- Added support for Django 5.2.
37+
38+
### Changed
39+
40+
- Bumped Rust toolchain from 1.83 to 1.86
41+
- Bumped PyO3 to 0.24.
42+
- **Internal**: Renamed template parsing crate to `djls-templates`
43+
- **Internal**: Swapped from `tower-lsp` to `tower-lsp-server` for primary LSP framework.
44+
45+
### Removed
46+
47+
- Dropped support for Django 5.0.
48+
49+
## [5.1.0a2]
50+
51+
### Added
52+
53+
- Support for system-wide installation using `uv tool` or `pipx` with automatic Python environment detection and virtualenv discovery
54+
55+
### Changed
56+
57+
- Server no longer requires installation in project virtualenv, including robust Python dependency resolution using `PATH` and `site-packages` detection
58+
59+
## [5.1.0a1]
60+
61+
### Added
62+
63+
- Basic Neovim plugin
64+
65+
## [5.1.0a0]
66+
67+
### Added
68+
69+
- Created basic crate structure:
70+
- `djls`: Main CLI interface
71+
- `djls-project`: Django project introspection
72+
- `djls-server`: LSP server implementation
73+
- `djls-template-ast`: Template parsing
74+
- `djls-worker`: Async task management
75+
- Initial Language Server Protocol support:
76+
- Document synchronization (open, change, close)
77+
- Basic diagnostics for template syntax
78+
- Initial completion provider
79+
- Basic Django template parsing foundation and support
80+
- Project introspection capabilities
81+
- Django templatetag completion for apps in a project's `INSTALLED_APPS`
82+
83+
### New Contributors
84+
85+
- Josh Thomas <[email protected]> (maintainer)
86+
87+
[unreleased]: https://github.com/joshuadavidthomas/django-language-server/compare/v5.2.0a0...HEAD
88+
[5.1.0a0]: https://github.com/joshuadavidthomas/django-language-server/releases/tag/v5.1.0a0
89+
[5.1.0a1]: https://github.com/joshuadavidthomas/django-language-server/releases/tag/v5.1.0a1
90+
[5.1.0a2]: https://github.com/joshuadavidthomas/django-language-server/releases/tag/v5.1.0a2
91+
92+
[5.2.0a0]: https://github.com/joshuadavidthomas/django-language-server/releases/tag/v5.2.0a0

‎docs/development/index.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
---
2+
title: Overview
3+
---
4+
# Development
5+
6+
The project is written in Rust using PyO3 for Python integration. Here is a high-level overview of the project and the various crates:
7+
8+
- Main CLI interface ([`crates/djls/`](./crates/djls/))
9+
- Django and Python project introspection ([`crates/djls-project/`](./crates/djls-project/))
10+
- LSP server implementation ([`crates/djls-server/`](./crates/djls-server/))
11+
- Template parsing ([`crates/djls-templates/`](./crates/djls-templates/))
12+
- Tokio-based background task management ([`crates/djls-worker/`](./crates/djls-worker/))
13+
14+
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.
15+
16+
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‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
---
2+
title: Releasing a New Version
3+
---
4+
5+
<!--
6+
THIS FILE IS AUTO-GENERATED
7+
DO NOT EDIT THIS FILE DIRECTLY
8+
Generated via docs/processor.py from RELEASING.md
9+
-->
10+
11+
# Releasing a New Version
12+
13+
## Create Release Branch
14+
15+
Create a new git branch off of `main` for the release.
16+
17+
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).
18+
19+
```bash
20+
git checkout -b release/v<version>
21+
```
22+
23+
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.
24+
25+
## Update Documentation
26+
27+
### Run cog
28+
29+
```bash
30+
uv run --with bumpver --with cogapp --with nox cog -r <COG_FILES>
31+
```
32+
33+
### Convert GitHub-Flavored Markdown to Mkdocs
34+
35+
```bash
36+
uv run docs/processor.py
37+
```
38+
39+
## Update CHANGELOG
40+
41+
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.
42+
43+
## Bump Version Number
44+
45+
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.
46+
47+
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.
48+
49+
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.
50+
51+
**Note**: For any of the following commands, you can add the command line flag `--dry` to preview the changes without actually making the changes.
52+
53+
Here are the most common commands you will need to run:
54+
55+
```bash
56+
uv run --with bumpver bumpver update --patch # for a patch release
57+
uv run --with bumpver bumpver update --minor # for a minor release
58+
uv run --with bumpver bumpver update --major # for a major release
59+
```
60+
61+
To release a tagged version, such as a beta or release candidate, you can run:
62+
63+
```bash
64+
uv run --with bumpver bumpver update --tag=beta
65+
# or
66+
uv run --with bumpver bumpver update --tag=rc
67+
```
68+
69+
Running these commands on a tagged version will increment the tag appropriately, but will not increment the version number.
70+
71+
To go from a tagged release to a full release, you can run:
72+
73+
```bash
74+
uv run --with bumpver bumpver update --tag=final
75+
```
76+
77+
### Choosing the Next Version Number
78+
79+
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).
80+
81+
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.
82+
83+
## Update `uv.lock`
84+
85+
```bash
86+
uv lock
87+
```
88+
89+
## Create Release PR
90+
91+
Create a pull request from the release branch to `main`.
92+
93+
Once CI has passed and all the checks are green ✅, merge the pull request.
94+
95+
## Create New GitHub Release
96+
97+
### Using CLI
98+
99+
```bash
100+
gh release create v<version> --generate-notes
101+
```
102+
103+
If this is a tagged version (e.g. `alpha` or `beta`), make sure to call the create command with the `--prerelease` flag:
104+
105+
```bash
106+
gh release create v0.0.0a0 --generate-notes --prerelease
107+
```
108+
109+
### Using Web
110+
111+
Draft a [new release](https://github.com/joshuadavidthomas/django-language-server/releases/new) on GitHub.
112+
113+
Use the version number with a leading `v` as the tag name (e.g. `v0.1.0`).
114+
115+
Allow GitHub to generate the release title and release notes, using the 'Generate release notes' button above the text box.
116+
117+
If this is a tagged version (e.g. `alpha` or `beta`), make sure to check the 'Set as a pre-release' checkbox.
118+
119+
## Publish to PyPI
120+
121+
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‎

Lines changed: 23 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -507,6 +507,24 @@ def main():
507507
],
508508
)
509509

510+
changelog = File(
511+
input_path="CHANGELOG.md",
512+
output_path="docs/changelog.md",
513+
processors=[
514+
*common_processors,
515+
add_frontmatter({"title": "Changelog"}),
516+
],
517+
)
518+
519+
release = File(
520+
input_path="RELEASING.md",
521+
output_path="docs/development/releasing.md",
522+
processors=[
523+
*common_processors,
524+
add_frontmatter({"title": "Releasing a New Version"}),
525+
],
526+
)
527+
510528
nvim = File(
511529
input_path="editors/nvim/README.md",
512530
output_path="docs/editors/neovim.md",
@@ -518,14 +536,18 @@ def main():
518536

519537
# Process files
520538
readme_success = readme.process(preview=True)
539+
changelog_success = changelog.process(preview=True)
540+
release_success = release.process(preview=True)
521541
nvim_success = nvim.process(preview=True)
522542

523-
if readme_success and nvim_success:
543+
if readme_success and changelog_success and release_success and nvim_success:
524544
console.print("\n[green]✨ All files processed successfully![/green]")
525545
else:
526546
console.print("\n[red]Some files failed to process:[/red]")
527547
for name, success in [
528548
("README.md → docs/index.md", readme_success),
549+
("CHANGELOG.md → docs/changelog.md", changelog),
550+
("RELEASING.md → docs/development/releasing.md", release_success),
529551
("Neovim docs → docs/editors/neovim.md", nvim_success),
530552
]:
531553
status = "[green]✓[/green]" if success else "[red]✗[/red]"

0 commit comments

Comments
 (0)