Creative Commons (CC) Legal Tools Application. This repository contains the application that manages the license tools and public domain tools (static HTML, internationalization and localization files, etc.). It consumes and generates data in the creativecommons/cc-legal-tools-data repository.
The Creative Commons team is committed to fostering a welcoming community. This project and all other Creative Commons open source projects are governed by our Code of Conduct. Please report unacceptable behavior to conduct@creativecommons.org per our reporting guidelines.
This application manages 639 legal tools (636 licenses and 3 public domain tools). The current version of the licenses is 4.0 and includes 6 licenses. They are international and are designed to operate globally, ensuring they are robust, enforceable and easily adopted worldwide. Prior versions were adapted to specific jurisdictions ("ported"). That is why there are 636 licenses.
Broadly speaking, each legal tool consists of three layers:
deed: a plain language summary of the legal toollegalcode: the legal tool itselfrdf: metadata about the legal tool in RDF/XML format
With translations of the deed and translations of the legal code, this application manages over 30,000 documents.
This project is not intended to serve the legal tools directly. Instead, a command line tool can be used to save all the rendered HTML and RDF/XML pages as files. Then those files are used as part of the CreativeCommons.org site (served as static files).
Once this project's required dependencies (Docker, Git, etc.) are enabled on your system, you will be able to run the legal-tools application and generate static files.
For information on learning and installing the prerequisite technologies for this project, please see Foundational technologies — Creative Commons Open Source.
Both this repository and the creativecommons/cc-legal-tools-data project repository should be cloned side by side, resulting in a structure like the following:
creative-commons/
├── cc-legal-tools-app/ (git clone of this repository)
└── cc-legal-tools-data/ (git clone of the cc-legal-tools-data repository)
To achieve this, we recommend the following procedure:
- Create and change to a container directory, such as
creative-commonsorcc.mkdir creative-commons cd creative-commons - Clone both repos using SSH or, if that does not work, HTTPS protocol.
or
git clone git@github.com:creativecommons/cc-legal-tools-app.git git clone git@github.com:creativecommons/cc-legal-tools-data.git
git clone https://github.com/creativecommons/cc-legal-tools-app.git git clone https://github.com/creativecommons/cc-legal-tools-data.git
Visit Cloning a repository - GitHub Docs for more on how to clone a GitHub repository.
Use the following instructions to prepare and run the project with Docker Compose.
- Ensure all prerequisites and repositories are in place.
- Ensure you are at the top level of the directory where you cloned this
repository (where
manage.pyis).cd cc-legal-tools-app - Create Django local settings file from the example file.
cp cc_legal_tools/settings/local.example.py cc_legal_tools/settings/local.py
- Update variables in new file, if necessary.
- This file is ignored by Git.
- Build the containers.
docker compose build
- Run the containers.
docker compose up
- app (127.0.0.1:8005): this Django
application
- Any changes made to Python will be detected and rebuilt transparently as long as the development server is running.
- static (127.0.0.1:8006): a static web
server serving creativecommons/cc-legal-tools-data:
docs/
- app (127.0.0.1:8005): this Django
application
- Initialize data.
Open a separate terminal tab, and in the same directory, run:
./dev/init_data.sh
- Deletes database (which may not yet exist)
- Initializes database
- Performs database migrations
- Creates supseruser (will prompt for password)
- Loads data
Note: Once this full setup is performed, running Step 5 above will execute the application on any subsequent occasion.
With the prerequisites installed and built, these tools can be used to generate and manage data from the associated data repository.
The legal tools metadata is in a database. The metadata tracks which legal tools exist, their translations, their ports, and their characteristics like what they permit, require, and prohibit.
The metadata can be downloaded by visiting the URL path:
(currently disabled)127.0.0.1:8005/licenses/metadata.yaml
There are two main models (Django terminology for tables) in
legal_tools/models.py:
LegalCodeTool
A Tool can be identified by a unit (ex. by, by-nc-sa, devnations) which
is a proxy for the complete set of permissions, requirements, and prohibitions;
a version (ex. 4.0, 3.0), and an optional jurisdiction for ports. So we
might refer to the tool by its identifier "BY 3.0 AM" which would be the
3.0 version of the BY license terms as ported to the Armenia jurisdiction. For
additional information see: Legal Tools Namespace -
creativecommons/cc-legal-tools-data: CC Legal Tools Data (static HTML, language
files, etc.).
There are three places legal code text could be:
- Gettext files (
.poand.mo) in the creativecommons/cc-legal-tools-data repository (legal tools with full translation support):- 4.0 Licenses
- CC0
- Django template
(
legalcode_licenses_3.0_unported.html):- Unported 3.0 Licenses (English-only)
htmlfield (in theLegalCodemodel):- Everything else
The text that's in gettext files can be translated via Transifex at Creative Commons localization. For additional information on the Django translation domains / Transifex resources, see How the license translation is implemented, below.
Documentation:
Generating static files updates the static files in the docs/ directory of
the creativecommons/cc-legal-tools-data repository (the Data
Repository, above).
This process will write the HTML files in the cc-legal-tools-data clone
directory under docs/. It will not commit the changes (--nogit) and will
not push any commits (--nopush is implied by --nogit).
- Ensure the Data Repository, above, is in place
- Ensure Docker Compose Setup, above, is complete
- Delete the contents of the
docs/directory and then recreate/copy the static files it should contain:docker compose exec app ./manage.py publish -v2
When the site is deployed, to enable pushing and pulling the licenses data repo
with GitHub, create an SSH deploy key for the cc-legal-tools-data repo with
write permissions, and put the private key file (not password protected)
somewhere safe (owned by www-data if on a server), and readable only by its
owner (0o400). Then in settings, make TRANSLATION_REPOSITORY_DEPLOY_KEY be
the full path to that deploy key file.
- Beautiful Soup Documentation — Beautiful Soup 4 documentation
- GitPython Documentation — GitPython documentation
For details and history, see docs/rdf.md.
Inside the Docker container, the Python-based tooling centers around by pre-commit and Django.
See the Code of Conduct above and the Code of Conduct document for more information on participant expectations and responsibilities.
See CONTRIBUTING.md.
⚠️ This section may be helpful for maintaining the project, but should NOT be used for development. Please use the Docker Compose Setup, above.
- Complete Docker Compose Setup, above
- Development Environment
- Install dependencies
- Linux:
sudo apt-get install python3.11 python3.11-dev python3-pip
pip3 install pipenv
- macOS: via Homebrew:
brew install pipenv python@3.11
- Windows: install Python and then use
pipto installpipenv:pip install pipenv
- Linux:
- Install Python environment and modules via pipenv to create a
virtualenv
- Linux:
pipenv install --dev --python /usr/bin/python3.11
- macOS: via Homebrew:
pipenv install --dev --python /usr/local/opt/python@3.11/libexec/bin/python
- Windows:
pipenv install --dev --python \User\Appdata\programs\python
- Linux:
- Install pre-commit hooks
pipenv run pre-commit install
- Install dependencies
- Run development server (127.0.0.1:8005)
pipenv run ./manage.py runserver
- Any changes made to Python will be detected and rebuilt transparently as long as the development server is running.
These are the currently designated versions of the various dependencies:
- Python 3.11 specified in:
- Django 4.2 (LTS)
These resources are available for developing this tooling:
- Python Guidelines — Creative Commons Open Source
- Black: the uncompromising Python code formatter
- Coverage.py: Code coverage measurement for Python
- Docker
- flake8: a python tool that glues together pep8, pyflakes, mccabe, and third-party plugins to check the style and quality of some python code.
- isort: A Python utility / library to sort imports.
- pre-commit: A framework for managing and maintaining multi-language pre-commit hooks.
ℹ️ The rest of the documentation assumes Docker. If you are using a manual setup, use
pipenv runinstead ofdocker compose exec appfor the commands below.
Best run before every commit:
./dev/coverage.sh- Run coverage tests and report./dev/tools.sh- Run Python code tools (isort, black, flake8)
Run as needed:
./dev/copy_theme.sh- Copy the portions of creativecommons/vocabulary-theme needed for local development- Run after each new release of creativecommons/vocabulary-theme
Data management:
./dev/dump_data.sh- Dump Django application data./dev/init_data.sh-⚠️ Initialize Django application data./dev/load_data.sh- Load Django application data
Esoteric and dangerous:
./dev/updatemessages.sh-⚠️ Run Django Management nofuzzy_makemessages with helpful options (including excluding legalcode) and compilemessages
The coverage tests and report are run as part of pre-commit and as a GitHub Action. To run it manually:
- Ensure the Data Repository, above, is in place
- Ensure Docker Compose Setup, above, is complete
- Coverage test
docker compose exec app coverage run manage.py test --noinput --keepdb
- Coverage report
docker compose exec app coverage report
If you encounter an error: Error building trees error from pre-commit when
you commit, try adding your files (git add <FILES>) before committing them.
The following CC projects are used to achieve a consistent look and feel:
- creativecommons/vocabulary-theme: WordPress Theme implementation of the Vocabulary design system
LICENSE: the code within this repository is licensed under the
Expat/MIT license.
The text of the Creative Commons public licenses (legal code) is dedicated to the public domain under the CC0 1.0 Universal (CC0 1.0) Public Domain Dedication.
COPYING: All the code within Vocabulary is dedicated to
the public domain under the CC0 1.0 Universal (CC0 1.0) Public Domain
Dedication.
normalize.css is licensed under the Expat/MIT License.
Accidenz Commons by Archetypo is licensed under the Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0) License.
JetBrains Mono is licensed under the OFL-1.1 License.
Roboto Condensed by Christian Robertson is licensed under the Apache License, Version 2.0.
Source Sans Pro by Paul D. Hunt is licensed under the Open Font License.
Vocabulary Icons use icons from Font Awesome which are licensed under the Creative Commons Attribution 4.0 International (CC BY 4.0) License.