This repo contains tooling for maintaining Liferay's customized version of CKEditor.
ckeditor-dev
pointing at the upstream CKEditor project.patches/
directory containing Liferay-specific changes to be applied to the upstream.skins/
directory containing custom skins.ck.sh
script for setting up the project, creating/updating patches, and producing releases.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:
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.With those basic operations in place, the most common workflows are described in the following sections:
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-pick
ing 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.
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.
./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:
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.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../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.To test your local CKEditor build in liferay-portal:
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.
editor.wysiwyg.portal-web.docroot.html.portlet.blogs.edit_entry.jsp=ckeditor
to test CKEditor in the [Site] → "Content & Data" → "Blogs" interface.Navigate to the frontend-editor-ckeditor-web module
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).
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
.
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.
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 git@github.com
yarn login
# Publish
yarn version --new-version $VERSION
Running yarn version
has the following effects:
yarn ci
again.git push
and performs a yarn publish
, prompting for confirmation along the way.Paste the relevant section from the CHANGELOG.md to the corresponding release page.
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).
After the release, you can confirm that the packages are correctly listed in the NPM registry:
For tagging and publishing $VERSION
should be of the form $CKEDITOR_VERSION-liferay.$RELEASE
. For example, "4.11.3-liferay.1"; that is:
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.
To update CKEditor in liferay-portal:
liferay-ckeditor
dependency in using yarn add liferay-ckeditor@$VERSION
.gradlew clean deploy
.An example of this can be seen in this PR.
./ck.sh createskin
./skins/yourskin
folder../ck.sh build
.