Skip to content

Legal tool (licenses, public domain dedication, etc.) management application for Creative Commons

License

Notifications You must be signed in to change notification settings

anikaymaasquesa/cc-legal-tools-app

 
 

Repository files navigation

cc-legal-tools-app

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.

Code of conduct

CODE_OF_CONDUCT.md:

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 [email protected] per our reporting guidelines.

Contributing

See CONTRIBUTING.md.

About

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:

  1. deed: a plain language summary of the legal tool
  2. legalcode: the legal tool itself
  3. rdf: 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.

Not the live site

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).

Software Versions

Setting up the Project

Data Repository

Visit Cloning a Repository on how to clone a GitHub repository.

The creativecommons/cc-legal-tools-data project repository should be cloned into a directory adjacent to this one:

PARENT_DIR
├── cc-legal-tools-app     (git clone of this repository)
└── cc-legal-tools-data    (git clone of the cc-legal-tools-data repository)

If it is not cloned into the default location, the Django DATA_REPOSITORY_DIR Django configuration setting, or the DATA_REPOSITORY_DIR environment variable can be used to configure its location.

Docker Compose Setup

Use the following instructions to start the project with Docker compose. Pleaes note that CC staff use macOS for development--please help us with documenting other operating systems if you encounter issues.

  1. Ensure the Data Repository, above, is in place
  2. Install Docker Engine
  3. Ensure you are at the top level of the directory where you cloned this repository (where manage.py is)
  4. Create Django local settings file
    cp cc_legal_tools/settings/local.example.py cc_legal_tools/settings/local.py
    • Update variables in new file, as necessary
  5. Build the containers
    docker compose build
  6. Run the containers
    docker compose up
    1. 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.
    2. static (127.0.0.1:8006): a static web server serving creativecommons/cc-legal-tools-data:docs/
  7. Initialize data
    ./dev/init_data.sh
    1. Delete database (which may not yet exist)
    2. Initialize database
    3. Perform databsea migrations
    4. Crate supseruser (will prompt for password)
    5. Load data

Manual Setup

⚠️ This section may be helpful for maintaining the project, but should NOT be used for development. Please use the Docker Compose Setup, above.

  1. Complete Docker Compose Setup, above
  2. Development Environment
    1. Install dependencies
      • Linux:
        sudo apt-get install python3.11 python3.11-dev python3-pip
        pip3 install pipenv
      • macOS: via Homebrew:
        brew install pipenv [email protected]
      • Windows: install Python and then use pip to install pipenv:
        pip install pipenv
    2. 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/[email protected]/libexec/bin/python
      • Windows:
        pipenv install --dev --python \User\Appdata\programs\python
    3. Install pre-commit hooks
    pipenv run pre-commit install
  3. 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.

Manual Commands

ℹ️ The rest of the documentation assumes Docker. If you are using a manual setup, use pipenv run instead of docker compose exec app for the commands below.

Tooling

Helper Scripts

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:

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

Coverage Tests and Report

The coverage tests and report are run as part of pre-commit and as a GitHub Action. To run it manually:

  1. Ensure the Data Repository, above, is in place
  2. Ensure Docker Compose Setup, above, is complete
  3. Coverage test
    docker compose exec app coverage run manage.py test --noinput --keepdb
  4. Coverage report
    docker compose exec app coverage report

Commit Errors

Error building trees

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.

Frontend Dependencies

The following CC projects are used to achieve a consistent look and feel:

Data

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: 127.0.0.1:8005/licenses/metadata.yaml (currently disabled)

There are two main models (Django terminology for tables) in legal_tools/models.py:

  1. LegalCode
  2. Tool

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:

  1. Gettext files (.po and .mo) in the creativecommons/cc-legal-tools-data repository (legal tools with full translation support):
    • 4.0 Licenses
    • CC0
  2. Django template (legalcode_licenses_3.0_unported.html):
    • Unported 3.0 Licenses (English-only)
  3. html field (in the LegalCode model):
    • 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:

Translation

See docs/translation.md

Generate Static Files

Generating static files updates the static files in the docs/ directory of the creativecommons/cc-legal-tools-data repository (the Data Repository, above).

Static Files Process

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).

  1. Ensure the Data Repository, above, is in place
  2. Ensure Docker Compose Setup, above, is complete
  3. 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

Publishing changes to git repo

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.

Publishing Dependency Documentation

Machine/metadata layer: RDF/XML

For details and history, see docs/rdf.md.

Licenses

Code

LICENSE: the code within this repository is licensed under the Expat/MIT license.

Legal Code text

CC0 1.0 Universal (CC0 1.0) Public Domain Dedication button

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.

vocabulary-theme

CC0 1.0 Universal (CC0 1.0) Public Domain Dedication button

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

normalize.css is licensed under the Expat/MIT License.

Fonts

Accidenz Commons

Accidenz Commons by Archetypo is licensed under the Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0) License.

JetBrains Mono

JetBrains Mono is licensed under the OFL-1.1 License.

Roboto Condensed

Roboto Condensed by Christian Robertson is licensed under the Apache License, Version 2.0.

Source Sans Pro

Source Sans Pro by Paul D. Hunt is licensed under the Open Font License.

Vocabulary Icons

Vocabulary Icons use icons from Font Awesome which are licensed under the Creative Commons Attribution 4.0 International (CC BY 4.0) License.

About

Legal tool (licenses, public domain dedication, etc.) management application for Creative Commons

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • Python 67.9%
  • HTML 17.7%
  • CSS 10.3%
  • Shell 3.8%
  • Other 0.3%