README.md

liferay-ckeditor

This repo contains tooling for maintaining Liferay's customized version of CKEditor.

Structure

• A submodule at ckeditor-dev pointing at the upstream CKEditor project.
• A patches/ directory containing Liferay-specific changes to be applied to the upstream.
• A skins/ directory containing custom skins.
• A ck.sh script for setting up the project, creating/updating patches, and producing releases.
• A ckeditor directory containing the committed build artifacts.

For details on why we settled on this approach, please see issues #7, #16 and #66 but in short, the desired attributes are:

• Make Liferay-specific patches easy to inspect by aggregating them into a directory.
• Make changes in patches over time obvious (by inspecting their history).
• Make changes in build artifacts obvious (again, but inspecting their history).
• Make possible to create custom skins.

How it works

• The ckeditor-dev submodule always points at the pristine (unmodified) upstream CKEditor repository, and specifically, at a release tag.
• ck.sh setup makes sure the submodule is up-to-date, creates a "liferay" branch inside it, and applies patches from the "patches/" directory to that branch.
• ck.sh patch freshens the contents of the "patches/" directory based on the current contents of the "liferay" branch in the submodule.
• ck.sh update updates to a requested version of CKEditor and rebases the contents of the "patches/" directory onto the new version.
• ck.sh build produces a build based on the current contents of the submodule, writing the files out to the "ckeditor/" directory and committing the result.
• ck.sh createskin creates a copy of CKEditor's moono-lisa base skin on /skins folder with the provided name.

Common scenarios

With those basic operations in place, the most common workflows are described in the following sections:

• Creating a new patch to CKEditor
• Updating the base version of CKEditor
• Testing in liferay-portal
• Publishing the liferay-ckeditor package to NPM
• Updating CKEditor in liferay-portal
• Creating and building a custom skin

Creating a new patch to CKEditor

These are the steps you would follow, for example, to apply a workaround for a bug in the upstream project:

• Make sure you're up-to-date with the superproject repository:

  git pull origin master

• Set up everything to start working on a patch:

  ./ck.sh setup

• Work on your changes:

  cd into the ckeditor-dev/ submodule and prepare your desired changes on the liferay branch.

  This could be cherry-picking a previously created commit or manually editing a file, so this can't be automated.

• Create your commit, add your changes and write a good commit message.

• Navigate back to the superproject's root directory and update the contents of the "patches/" directory:

  cd ..
  ./ck.sh patch

• Create a build of CKEditor containing the patches:

  From the root of the superproject's directory, run

  ./ck.sh build

  If you'd rather like a development build, for example for local debugging, use:

  DEBUG=1 ./ck.sh build

  WARNING: You should never publish development builds to the npm registry.

• For non-development builds, the updated build artifacts will be committed automatically. Be aware that if you ever wish to stage and commit build artifacts by hand, you should do so using:

  git add ckeditor

  because variants such as git add ., git add -A, git add -f, git add -u etc can cause you to unintentionally modify the target of the ckeditor-dev submodule.

Updating the base version of CKEditor

To update the upstream CKEditor code to a new version, run:

./ck.sh update

A prompt will appear asking you which version you'd like to select. This will update the ckeditor-dev submodule to point at the corresponding commit.

NOTE: In order to prevent unintended commits to the submodule, using ck.sh update is the only supported way to change the commit the submodule is referencing. Git is configured to ignore changes to the submodule, so you will only see them in the output of commands like git status, git show, git log -p (etc) if you pass the --ignore-submodules=none switch.

Resolving problems while updating CKEditor's base version

./ck.sh update should only be used to check that everything is in order before applying changes, and we cannot expect it to be used to resolve conflicts.

You may encounter some issues throughout the upgrade process. You can take the following actions to properly resolve these conflicts:

1. Navigate to the ckeditor-dev/ subdirectory and manually resolve conflicts by rebasing with the proper tag/version you want to upgrade. git pull —rebase 4.18.0, for example, can be used to rebase with 4.18.0.
2. Go to liferay-ckeditor/ and run ./ck.sh update after the submodule has been successfully updated. Choose the correct version of ckeditor you're trying to update, then check to see if everything under ckeditor-dev is fine and without conflicts.
3. If everything looks good and there are no conflicts, run ./ck.sh patch to update the patches/ folder, and don't forget to leave a good commit message. chore: update patches for upgrading to CKEditor 4.18.0 is an example of a decent commit message for this type of change.

Testing in liferay-portal

To test your local CKEditor build in liferay-portal:

0. Make sure you have your liferay-portal instance configured to use CKEditor in at least one place by setting one of the appropriate properties in your portal-ext.properties file.

   • For example, you could set editor.wysiwyg.portal-web.docroot.html.portlet.blogs.edit_entry.jsp=ckeditor to test CKEditor in the [Site] → "Content & Data" → "Blogs" interface.
   • Ideally, you should also test that AlloyEditor still works too — for example, at [Site] → "Content & Data" → "Web Content" — because we have that configured to use the shared CKEditor build rather than its own bundled copy.

1. Navigate to the frontend-editor-ckeditor-web module

2. Run yarn add $PATH_TO_LOCAL_LIFERAY_CKEDITOR_REPO (in Liferay DXP and Portal CE 7.1 and above), or npm install $PATH_TO_LOCAL_LIFERAY_CKEDITOR_REPO (in Liferay DXP and Portal CE version 7.0).

3. Re-deploy the module with gradlew clean deploy.

Note: If you have problems with deploying after yarn add it may be that Gradle is confused by the reference to a local package. In this case, you may be able hackily workaround the problem, temporarily, by updating the node_modules directory manually instead:

rm -r modules/node_modules/liferay-ckeditor
cp -R $PATH_TO_LOCAL_LIFERAY_CKEDITOR_REPO modules/node_modules/

And resetting the changes in the package.json and yarn.lock files on the frontend-editor-ckeditor-web module caused by running yarn add.

Publishing the liferay-ckeditor package to NPM

1. Update, build and commit the result.

   # Confirm that worktree is clean and up-to-date.
   git checkout master
   git pull upstream master --ff-only
   git status
   
   # Build and commit.
   ./ck.sh build

   NOTE: Check that only files in ckeditor folder are being committed.

2. After successfully building and testing, you can publish to NPM, and update Git.

   # See all checks pass locally:
   yarn ci
   
   # See "Choosing a version number" below for guidance about the version number:
   VERSION=4.13.1-liferay.2
   
   # Update the CHANGELOG:
   npx liferay-changelog-generator --version=$VERSION
   
   # Inspect and add changes:
   git add -p CHANGELOG.md
   
   # Confirm you are logged in on Github and NPM
   ssh -T [email protected]
   yarn login
   
   # Publish
   yarn version --new-version $VERSION

   Running yarn version has the following effects:

   • The "preversion" script will run, which effectively runs yarn ci again.
   • The "package.json" gets updated with the new version number.
   • The "version" script will run, which checks that the proposed version number matches the expected format and corresponds to the version in the CKEditor submodule and build artifacts.
   • A tagged commit is created, including the changes to the CHANGELOG that you staged in a prior step.
   • The "postversion" script will run, which automatically does git push and performs a yarn publish, prompting for confirmation along the way.

3. Paste the relevant section from the CHANGELOG.md to the corresponding release page.

4. NOTE: One effect of using version numbers that include a -liferay suffix is that liferay-js-publish will interpret them as prerelease versions, in compliance with how NPM defines prerelease ranges (in agreement with the SemVer spec). This means that they will get a prelease tag in the NPM registry instead of the default latest tag. If you wish to, you can remove this unwanted prelease tag and point the latest tag at the version you just released with:

   npm dist-tag rm liferay-ckeditor prerelease
   npm dist-tag add liferay-ckeditor@$VERSION latest

   But in practice, this is optional because we always use an exact version specifier when referencing liferay-ckeditor from liferay-portal (example).

5. After the release, you can confirm that the packages are correctly listed in the NPM registry:

   • https://www.npmjs.com/package/liferay-ckeditor

Choosing a version number

For tagging and publishing $VERSION should be of the form $CKEDITOR_VERSION-liferay.$RELEASE. For example, "4.11.3-liferay.1"; that is:

• Based on CKEditor 4.11.3.
• Release number 1.

Subsequent releases would be "4.11.3-liferay.2", "4.11.3-liferay.3" and so on. When we update to CKEditor 4.11.4, we reset the suffix, so the release would be "4.11.4-liferay.1", "4.11.4-liferay.2" and so on.

WARNING: You should never publish development builds to the npm registry.

Updating CKEditor in liferay-portal

To update CKEditor in liferay-portal:

1. Navigate to the frontend-editor-ckeditor-web module
2. Update the liferay-ckeditor dependency in using yarn add liferay-ckeditor@$VERSION.
3. Re-deploy the module with gradlew clean deploy.

An example of this can be seen in this PR.

Creating and building a custom skin

1. Create a new skin running ./ck.sh createskin.
2. Edit the skin at /skins/yourskin folder.
3. Build the skin running ./ck.sh build.