Skip to content

Contributing

Jump to bottom
Marko Čikoš edited this page May 12, 2022 · 34 revisions

Contributing Guidelines

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.

Setup

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 build

To check if the setup finalized correctly, you can run tests:

yarn test

Repo organization

Branches

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

Key files and directories

  • 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 building lib/ckeditor and lib/ckeditor-debug (this is a submodule).
  • lib/lang: language strings from upstream CKEditor project.
  • src/adapter/main.js: defines the top-level AlloyEditor API.
  • src/assets/lang: defines AlloyEditor-specific strings.
  • src/components: React components for buttons and toolbars.
  • src/__generated__/lang: language files generated by yarn build:assets, combining strings specific to AlloyEditor (defined in "src/assets/lang") and upstream strings from CKEditor (defined in "lib/lang"), available as AlloyEditor.Strings.
  • src/plugins: CKEditor plugins for resizing, aligning, and so on.
  • test: the test suite.

Pull requests & Github issues

  • All pull requests should be sent to the master branch. The stable branch always reflects the most recent release.
  • Any merged changes will remain in the master branch 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 stable branch.
  • 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.

Tests

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.

Formatting

yarn format          # format all files
yarn format:changed  # format changed files
yarn format:check    # check the format of files but do not change them

Publishing a new release on the active development branch ("master")

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.

Before releasing

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

Releasing

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.

Updating Alloy Editor in DXP

Before updating:

  • Checkout upstream/master branch
  • 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-deduplicate

6. Update the release notes.

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

Variation: publishing a "pre"-release from the master branch for testing purposes

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 [email protected] prerelease

# ... and put the "latest" tag back where it belongs.
npm dist-tag add [email protected] 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.

Publishing a new release on the prior maintenance branch (currently, "1.x")

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.

0. Update the 1.x branch

git checkout 1.x
git pull upstream 1.x
git submodule update

1. Run tests

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

2. Update CHANGELOG.md

npx liferay-changelog-generator --version=$VERSION

Where $VERSION is the version you are about to release.

Review and stage the changes:

git add -p

3. Update npm version

yarn version --[patch|minor] # usually patch

4. Send a draft PR to 1.x-stable 

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

5. Publish npm module

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.

Updating CKEditor.

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

7. Run npm run build and have a look at the demo to make sure everything is working correctly.

Clone this wiki locally