Thank you for your interest in contributing to CC Open Source! This document is a set of guidelines to help you contribute to this project.
There are many ways to contribute to this project such as testing, design, and development.
By participating in this project, you are expected to uphold our Code of Conduct.
Please follow the processes in our general Contributing Code guidelines on the Creative Common Open Source website.
Talk to us on one of our community forums.
This section provides information for people who are interested in contributing code.
Install Docker (Install Docker Engine | Docker Documentation) and Docker Compose (Install Docker Compose | Docker Documentation).
References:
Alternatively, you can use the browser-based development environment described below.
You may use a browser-based development environment instead of installing Docker and Docker Compose locally. Just click the "Develop with Gitpod" button below to launch a pre-configured development environment. Once the environment opens in your browser, continue with the following sections (skipping sections handled automatically by Gitpod as noted).
Note: this step is handled automatically in the browser-based development environment.
This project consists of several components, such as WordPress themes, that are developed in their own Git repositories. If you have already cloned this project's code, make sure the Git sub-modules are activated by running the following command.
git submodule update --init
Alternatively, you can initialize the submodules when you clone the repository with the following command.
git clone --recursive
The Git submodule projects are under active development. When the submodule code changes, we can update our project to track the latest changes using the following command.
git submodule update --remote --merge
There are several optional environment variables used in the
docker-compose.yml
file. If you need, you can copy the .env.example
to
.env
and override the variables. Otherwise, the defaults should work fine.
The optional .env
file may contain a variable called DATABASE
. The value of
DATABASE
will determine which database is used for development (mysql
or
mariadb
). By default, we use mariadb
but you can change this to mysql
if
desired.
If you change the value of the DATABASE
variable at any time during
development, you will need to remove the old database volume in order and
rebuild the images to prevent errors.
- list all Docker volumes to find the relevant volume
docker volume ls
- remove the volume
docker volume rm <volume-id>
- rebuild the docker image
docker compose up --build -d
If you are actively developing the CC Legal Tools, your experience may be improved by replacing the submodule with a symlink (:warning: be careful not to commit this change):
rm -rf cc-legal-tools-data; ln -s ../cc-legal-tools-data .
You can revert the change with:
rm cc-legal-tools-data; git restore cc-legal-tools-data; git submodule update --init
Once you have installed the above development dependencies, you can run the following commands from within this project directory.
Note: this step is handled automatically in the browser-based development environment.
docker compose up
The command above will create a variety of docker services:
- wordpress (127.0.0.1:8000)
- database (also available directly on port
3306
) - phpmyadmin (127.0.0.1:8003)
- composer
docker compose down
- Ensure the docker services are running (Start the server, above)
- Simply run the helper script:
./setup-wordpress.sh
If you want to run WPI CLI commands manually, the following alias will make it much easier:
alias wp="docker compose run --rm wordpress-cli --url='http://127.0.0.1:8000'"
Verify the alias:
wp --info
Note: The WP CLI process, above, is preferred.
If you are starting the WordPress service for the first time, you will see the WordPress installation wizard:
Complete the installation process and make note of your username and password so that you can log in (below).
Alternatively, see the WordPress CLI section below for an example of how to install WordPress via the command line.
With the development server running, log in to the local WordPress with the login credentials you created during the WordPress installation:
Once you are logged in with your admin user (above), you can access the WordPress admin area:
From the WordPress admin area, you can activate the Creative Commons WordPress child theme from the Theme Settings and Plugins pages respectively. Note, some plugins may be automatically enabled by our Docker compose service.
The child theme is called creativecommons.org Child theme
.
We have prepared some pre-existing content based on the desired page and URL
structure for the new Creative Commons website, which is located in the
content-import
folder in the file staging-content-import.xml
.
The WordPress documentation contains an article describing how to import content.
Alternatively, use the WordPress CLI to import the content. See the WordPress CLI instructions below.
The content importer contains a menu called "CC". The CC menu is intended to represent the main navigation. It will also be served via the API for downstream projects like the CC Global Headers.
Go to the Appearance -> Menus -> Manage Locations screen and make sure the CC menu is in the Main navigation location.
Visit the Permalink Settings page to enable clean URLs, such as might be used by external sites and services.
Alternatively, see the WordPress CLI section below for an example of how to enable clean URLs via command line.
This project contains the wp-plugin-cc-gutenberg-blocks
project as a Git
submodule. Do the following, if you would like to develop CC Gutenberg blocks
in the context of project_creativecommons.org
.
- make sure you have completed all of the above steps so the Docker Compose project is running
- open a new teminal
- change directory
cd
intowp-plugin-cc-gutenberg-blocks
- run
npm install
to install dependencies - run
npm start
to start the Gutenberg block development project
From there, you can make changes to files in
wp-plugin-cc-gutenberg-blocks/src/
that will automatically build. Commits
made to that submodule can be pushed to branches in the upstream project as
well.