diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..ab9a62d6 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,45 @@ +# Contributing +We maintain tags on [our issues](https://github.com/classy-python/ccbv/issues/) to make it easy to find ones that might suit newcomers to the project. +The [Low-hanging fruit tag](https://github.com/classy-python/ccbv/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22Low-hanging%20fruit%22) is a good place to start if you're unfamiliar with the project. + +> [!NOTE] +> TLDR: The project is currently undergoing an overhaul behind the scenes with the goal of removing the need to use Django to serve pages. +> Check that your changes are still relevant with that in mind! +> +> CCBV runs as a Django site, pulling data from a database. +> 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 Django's generic class based views (GCBVs) only happen when Django makes a new release. +> We do not need to dynamically construct templates from the data on every request. +> We can write out some HTML and never touch it again (unless we feel like changing the site's styles!) +> The inspection code is tightly coupled to Django's GCBVs. +> There have been sites for other Django-specific class hierarchies using forks of CCBV for years. +> Other class hierarchies exist in Python. +> Work has been ongoing to reduce the coupling of the site to Django, with the goal of eventually completely removing it. +> This will help both this project and any related ones to more quickly update after Django or library releases, and also open up opportunities for other projects to grow. + +## Installation +Set up a virtualenv and run: + + make build + +This will install the requirements, collect static files, migrate the database, and finally load all the existing fixtures into your database. + +## Updating requirements +Add or remove the dependency from either `requirements.prod.in` or `requirements.dev.in` as appropriate. + +Run `make compile` and appropriate txt file will be updated. + +## Add data for new versions of Django +1. Update the `requirements.prod.in` file to pin the new version of Django, eg `django==5.1` +1. Run `make compile` to compile this change to `requirements.prod.txt` +1. Run `python manage.py populate_cbv` to introspect the installed Django and populate the required objects in the database +1. Run `python manage.py fetch_docs_urls` to update the records in the database with the latest links to the Django documentation, this will fail at 1.9, this is expected +1. Export the new Django version into a fixture with `python manage.py cbv_dumpversion x.xx > cbv/fixtures/x.xx.json` +1. Remove the empty Generic module from the generated JSON +1. Add the fixture to git with `git add cbv/fixtures/.git` +1. Restore the requirements files with `git restore requirements.*` +1. Commit and push your changes, they will be deployed once your PR is merged to main + +## Testing +Run `make test` to run the full test suite with coverage. diff --git a/README.markdown b/README.markdown deleted file mode 100644 index db5fe5e5..00000000 --- a/README.markdown +++ /dev/null @@ -1,111 +0,0 @@ -# Django Class Based Views Inspector - -Use the [Django Class Based Views Inspector](http://ccbv.co.uk/) - -## What's a class based view anyway? - -Django 1.3 came with class based generic views. These are really awesome, and -very powerfully coded with mixins and base classes all over the shop. This -means they're much more than just a couple of generic shortcuts, they also -provide utilities which can be mixed in the much more complex views that you -write yourself. - -## Great! So what's the point of the inspector? - -All of this power comes at the expense of simplicity. Trying to work out -exactly which method you need to customise on your `UpdateView` can feel a -little like wading through spaghetti - it has 8 separate ancestors (plus -`object`) spread across 3 different files. So working out that you wanted to -tweak `UpdateView.get_initial` and what it's keyword arguments are is a bit of -a faff. - -That's where this comes in! Here's the manifesto: - -> Provide an easy interface to learning the awesomeness of class based views. -> It should offer at least the ability to view the MRO of a generic view, all -> of the methods which are available on a particular class (including all -> inherited methods) complete with signature and docstrings. Ideally you should -> then be able to see where that method has come from, and any `super` calls -> it's making should be identified. Wrap this all up in a shiny front end! - -## Tools to consider - -* Python's built in [inspect](http://docs.python.org/library/inspect.html) - module to work out what's going on and put it in the database -* [JQuery](http://jquery.com) for shinyness -* [Backbone](http://documentcloud.github.com/backbone/) for JS structure -* [Piston](https://bitbucket.org/jespern/django-piston/wiki/Home) for API -* [SASS](http://sass-lang.com/)/LESS and/or - [Bootstrap](http://twitter.github.com/bootstrap/) to make CSS less painful - -## Installation - -First you should install some OS libraries required for some packages, this can vary with each OS, but if you're on Ubuntu 14.04, then this should do the trick for you: - - sudo apt-get install python3-dev libmemcached-dev zlib1g-dev libpq-dev - -After this, install as you normally would a Django site (requirements files are provided). - -e.g. (inside your virtualenv or whatever) - - [uv] pip install -r requirements.prod.txt -r requirements.dev.txt - -Prepare the database (assuming you've got required database) - - python manage.py migrate cbv - -Populate the database with fixtures, either all at once: - - python manage.py load_all_django_versions - -or one at a time, for example: - - python manage.py loaddata cbv/fixtures/1.8.json - python manage.py loaddata cbv/fixtures/1.9.json - -Collect static files (CSS & JS) - - python manage.py collectstatic - -Run server and play around - - python manage.py runserver - -If you hope to contribute any code, please install `pre-commit` before committing. - - pre-commit install - - -## Updating Requirements -Add or remove the dependency from either `requirements.prod.in` or `requirements.dev.in` as appropriate. - -Run `make compile` and appropriate txt file will be updated. - - -## Updating for New Versions of Django - -The procedure for updating for a new version of Django is as simple as: - -1. Update the `requirements.in` file to pin the required version of Django; -2. Use `pip-compile` to freshen requirements for the new version of Django; -3. Use `pip-sync` to update your virtual environment to match the newly compiled - `requirements.txt` file; -4. Update the project's code to run under the target version of Django, as - necessary; -5. Use `python manage.py populate_cbv` to introspect the running Django - and populate the required objects in the database; -6. Use `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`; - - -## Testing - -All you should do is: - - make test - -## License - -License is [BSD-2](http://opensource.org/licenses/BSD-2-Clause). - diff --git a/README.md b/README.md new file mode 100644 index 00000000..f613ee3c --- /dev/null +++ b/README.md @@ -0,0 +1,10 @@ +# [Classy Class Based Views](https://ccbv.co.uk) + +Django's Generic class-based views provide a lot of common functionality to users. +However, they are made up of up to twelve parent classes or mixins, at the time of writing. +Knowing what functionality comes from which parent class/mixin is a tricky proposition. + +CCBV provides a breakdown of each view's inheritance hierarchy, methods, and attributes. +This allows you to find this information without tracing through every file and base class. + +Interested in helping out? Check out our [contributor docs](CONTRIBUTING.md)!