Rewrite the README to be clear and succinct #246
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
@meshy – this is a rather drastic minimisation of the current README's content, but I think most of that is no longer relevant now that ccbv.co.uk is widely known, and the GCBVs have been around for 12 (!) years. What do you think? Am I missing anything? Could I take more out? Not relevant for this PR but I think we can script even more of the tooling around the project when I look at it from a docs perspective! |
meshy
reviewed
Apr 24, 2025
| > This made it very fast to get up and running, and easy to maintain for the Django-using developers, but it has been a thorn in the side of the project for years. | ||
| > The dataset is entirely fixed. | ||
| > Any changes to the GCBVs only happen in a release of Django. | ||
| > We do not need to dynamically construct templates from the data on every request. |
There was a problem hiding this comment.
Nitpick: I think we should make the implication explicit here: that we currently do this, and that's a problem.
Perhaps we should format this as explicit lists. (For want of better names:) Constraints (intentions?), and Known architectural issues.
CONTRIBUTING.md
Outdated
Comment on lines
33
to
39
| ## Add data for new versions of Django | ||
| 1. Update the `requirements.prod.in` file to pin the required version of Django | ||
| 2. Run `make compile` to compile this change to `requirements.prod.txt`. | ||
| 4. Update the project's code to run under the target version of Django, if necessary | ||
| 5. Run `python manage.py populate_cbv` to introspect the running Django and populate the required objects in the database | ||
| 6. Run `python manage.py fetch_docs_urls` to update the records in the database with the latest links to the Django documentation | ||
| 7. Export the new Django version into a fixture with: `python manage.py cbv_dumpversion x.xx > cbv/fixtures/x.xx.json` |
There was a problem hiding this comment.
Issue: We'll need to add something here about the extra manual step, or find a way to automate it. We can discuss this IRL.
This modernises the project's README to match the current state of the project (ie dropping tools we should look at), tidies up the prose to be more succinct, and splits out contribution docs to CONTRIBUTING.md. The contributor docs have been streamlined to point to the `make` commands where possible. I've also added a section from #245 on where the project is going. It's a long piece of work so my hope is this sets expectations without making the maintainers feel bad when folks raise a PR for defunct or soon-to-be-removed code paths.
This modernises the project's README to match the current state of the project (ie dropping tools we should look at), tidies up the prose to be more succinct, and splits out contribution docs to CONTRIBUTING.md. The contributor docs have been streamlined to point to the `make` commands where possible. I've also added a section from #245 on where the project is going. It's a long piece of work so my hope is this sets expectations without making the maintainers feel bad when folks raise a PR for defunct or soon-to-be-removed code paths.
ghickman
force-pushed
the
rewrite-readme
branch
from
6833662 to
daa65cf
Compare
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This modernises the project's README to match the current state of the project (ie dropping tools we should look at), tidies up the prose to be more succinct, and splits out contribution docs to CONTRIBUTING.md.
The contributor docs have been streamlined to point to the
makecommands where possible. I've also added a section from #245 on where the project is going. It's a long piece of work so my hope is this sets expectations without making the maintainers feel bad when folks raise a PR for defunct or soon-to-be-removed code paths.Fix: #239