-
Notifications
You must be signed in to change notification settings - Fork 282
Contributing
If you wish to contribute to AlloyEditor these guidelines will be important for you. They cover instructions for setup, information on how the repository is organized, as well as contribution requirements.
Run following commands from the repository root directory:
# Switch to nodejs v10
# We recommend using the `n` version manager.
sudo n 10
# Checkout repository
git checkout master
git pull upstream master
git submodule update
# Clean repository
git clean -fdx
# Install dependencies
yarn install
# Build repository
yarn buildTo check if the setup finalized correctly, you can run tests:
yarn test
-
master: active development branch. -
stable: points to the latest release; may be used as a base for preparing urgent hotfix releases. -
1.x: previous active development branch for prior major version (1.x series, less frequently updated, generally only with bug-fixes). -
1.x-stable: points to the latest 1.x release (less frequently updated).
With each major version release, new maintenance branches are created, and future development continues on "master". For example, when 3.0 is released, we will create "2.x" and "2.x-stable" branches, and proceed with development on "master", updating "stable" with each 3.x.y release.
-
dist/alloy-editor: target directory where bundles (alloy-editor-all.js and friends) are built. -
lib/ckeditor: production-ready built files from the upstream CKEditor project. -
lib/ckeditor-debug: built-but-unminified files from the upstream CKEditor project. -
lib/ckeditor-dev: source files for buildinglib/ckeditorandlib/ckeditor-debug(this is a submodule). -
lib/lang: language strings from upstream CKEditor project. -
src/adapter/main.js: defines the top-levelAlloyEditorAPI. -
src/assets/lang: defines AlloyEditor-specific strings.-
src/assets/lang/language.json: the canonical list of strings to be translated (via Crowdin); add new strings here.
-
-
src/components: React components for buttons and toolbars. -
src/__generated__/lang: language files generated byyarn build:assets, combining strings specific to AlloyEditor (defined in "src/assets/lang") and upstream strings from CKEditor (defined in "lib/lang"), available asAlloyEditor.Strings. -
src/plugins: CKEditor plugins for resizing, aligning, and so on. -
test: the test suite.
- All pull requests should be sent to the
masterbranch. Thestablebranch always reflects the most recent release. - Any merged changes will remain in the
masterbranch until the next scheduled release. - The only exception to this rule is for emergency hot fixes, in which case the pull request can be sent to the
stablebranch. - All commits in a given pull request should start with the
fix:,chore:,refactor:,test:,perf:,doc:etc, as per the Conventional Commits guidelines for traceability purposes.
Any change (be it an improvement, a new feature or a bug fix) needs to include a test, and all tests from the repo need to be passing. To run the tests you can use our script:
yarn test
This will run the complete test suite on Chrome. For a full test pass, you can add local browsers to the root karma.js file and re-run the command.
Additionally, you can also run the test suite via Saucelabs with the following npm script:
yarn test:saucelabs
This last command is the one used by our CI integration.
yarn format # format all files
yarn format:changed # format changed files
yarn format:check # check the format of files but do not change them
These instructions show the steps require to publish a new version on the active development branch (that is, "master", which currently corresponds to the v2.x series of releases). Later on in the document we describe how to produce a release on the previous branch (currently, the v1.x series of releases) in order to create a bug-fix release.
- Are there any pending Crowdin translations that should be merged? If so, merge them using the "Squash and merge" button; by avoiding a merge commit, we keep a useless "New Crowdin translations" entry out of the changelog.
Run following commands from the repository root directory:
# Update the `master` branch
git checkout master
git pull upstream master
git submodule update
# Run formatting, lint, build, and tests locally as a sanity check
yarn format:check # fix with "yarn format" if necessary
yarn lint:quiet
yarn build
yarn test # or "yarn test:debug" to inspect full log in browser console
# Create new maintenance branches, if appropriate
# As noted above, *if and only if this is a major release*, this is also the time to create the corresponding maintenance branches:
git branch 2.x
git branch 2.x-stable
git push upstream 2.x
git push upstream 2.x-stable
# Update changelog
# `$VERSION` is the version you are about to release
npx liferay-changelog-generator --version=$VERSION
# Review the changes.
# Use `git diff` to confirm that the CHANGELOG.md looks correct. Feel free to edit it if you want to make improvements. Then stage the changes:
git add CHANGELOG.md
# Tag and publish the new release.
yarn version --minor` # (or `--major`, or `--patch`, as appropriate).This will update the package.json and create a tagged commit, including the updates to the CHANGELOG that you previously made.
We use liferay-js-publish from the "postversion" script to take care of pushing to the repo, and actually publishing to the NPM registry; just follow the prompts.
Before updating:
- Checkout
upstream/masterbranch - Run
ant all
Alloy Editor in DXP is implemented in the frontend-editor-alloyeditor-web. In the root of this module, run:
yarn add alloyeditor@$VERSION After this navigate to /modules:
# Clean up dependencies. This will update the yarn.lock file.
yarn install
npx yarn-deduplicateTake the new section from the top of the CHANGELOG and add it to the release page on GitHub.
7. Sanity check the alloyeditor page on npmjs.com
Specifically, you should see the version you just released under the "Versions" tab on that page.
You may wish to publish a "pre"-release in order to test a specific PR before merging it. The following example assumes you have a local copy of the code on a branch in your repo (in this case, pull/1425).
⚠️ This is an advanced method, so proceed with care.
# Must be on "master" branch or liferay-js-publish will panic.
git checkout master
# In order to produce a changelog, you must use commit message
# in your merge commit that matches GitHub's format;
# liferay-changelog-generator relies on this:
#
# Merge pull request #1425 from NemethNorbert/LPS-120361
#
# fix: correct toolbar misalignment when editor is rendered in modal
#
git merge --no-ff pull/1425
# Update the changelog; note that prerelease version suffixes
# start with "-pre.0":
npx liferay-changelog-generator --version=v2.11.14-pre.0
git add -p
# Now cut the pre-release.
# IMPORTANT: answer "n" at the prompt unless you want this
# prerelease to go to master; for a "throwaway" test you
# probably don't.
#
# Push to upstream-rw/master? [y/n] n
#
yarn version --prepatch
# Even if you don't merge to master, you still need the tag
# to go to GitHub (we must not release code to npm without the
# source being publicly available).
#
# So, say the "liferay" remote is called "upstream", do the
# following.
git push upstream --tags --dry-run
git push upstream --tags
# Actually publish.
yarn publish --tag prerelease
# If you forget the "--tag", you'll have to add the "prerelease" tag...
npm dist-tag add alloyeditor@2.11.14-pre.0 prerelease
# ... and put the "latest" tag back where it belongs.
npm dist-tag add alloyeditor@2.11.13 latest
# Finally, make your master point back where it was before.
git reset --hard upstream/master
Remember to paste the release notes into the release page (example), and verify the npm registry page to confirm that the "latest" and "prerelease" tags are pointing at the correct releases (ie. the previous stable release, and your pre-release, respectively).
As noted inline, the above workflow can be modified to actually submit changes to the master branch. This is appropriate when you may want to do a series of pre-releases in succession, each building off the one before it.
Rarely, we may need to create a release on the previous release branch (currently, the "1.x" series of releases) in order to backport a bug-fix. The steps are similar to those described above in Publishing a new release on the active development branch ("master"), but with some minor distinctions.
git checkout 1.x
git pull upstream 1.x
git submodule update
Note that unlike the "master" branch, the "1.x" branch only offer a "test" script and does not have scripts for formatting and linting.
yarn test
npx liferay-changelog-generator --version=$VERSIONWhere $VERSION is the version you are about to release.
Review and stage the changes:
git add -pyarn version --[patch|minor] # usually patch
git push upstream 1.x
Once you have pushed to 1.x, you will create a draft PR that proposes merging 1.x into 1.x-stable. The purpose of this PR is to see all the tests pass in CI; you do not need to (and probably should not) actually merge it.
Instead, once the CI is green, close the PR and then push directly:
git checkout 1.x-stable
git merge --ff-only 1.x
git push upstream 1.x-stable --follow-tags
NOTE: We publish 1.x branches using the "v1.x" tag.
yarn publish --tag v1.x
6. Update GitHub release information using the pushed vX.X.X tag and the appropriate portion of CHANGELOG.md
See the Releases listing on GitHub.
To update to, for example, v4.11.2, run: scripts/build/build-ckeditor.sh 4.11.2 and commit the result. This is a wrapper for the ckbuilder tool.
If you wish to modify the wrapper, see other switches that can be passed to the underlying tool with:
java -jar lib/ckeditor-dev/dev/builder/ckbuilder/2.3.2/ckbuilder.jar