Contributing

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

TBD

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.
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/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 by npm run 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.
A Github issue should also be created for any bug fix or feature, this helps when generating the CHANGELOG.md file.
All commits in a given pull request should start with the Fixes #xxx - message 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 npm script:

npm 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:

npm testSaucelabs

This last command is the one used by our CI integration.

Formatting

TBD

JS Docs

All methods should be documented, following Google's format.

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.

0. Update the `master` branch

git checkout master
git pull upstream master

1. Run formatting, lint, build, and tests locally as a sanity check

npm run format:check # fix with `npm run format` if necessary
npm run lint:quiet
npm run build
npm run test # or npm run test:debug to inspect full log in browser console

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

3. Update npm version

npm version --no-git-tag-version patch|minor|major

Note: the use of --no-git-tag-version because we want to apply the tag only after we have updated the changelog and see our PR pass in CI.

4. Update the changelog

Previously, we used github_changelog_generator to update the changelog but we encountered a number of problems with it in various projects that involve multiple branches.

Until we find a better place for it, the liferay-js-themes-toolkit has a changelog.js script that has no dependencies and which you can use to update the changelog:

node changelog.js --version=$VERSION

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

5. Commit changelog

git add CHANGELOG.md
git commit -m "Updates CHANGELOG for vX.X.X"

6. Send release PR to `master`

7. Wait to see that all tests pass in CI and then merge

8. Pull `master` locally

git pull --ff-only upstream master

6. Rebuild the dist files

yarn build

9. Publish npm modules and push release tags

With a $VERSION of the format "vX.Y.Z" matching the one in the "package.json" file:

git tag $VERSION -m $VERSION
npm publish --dry-run # Final sanity check.
npm publish
git push --follow-tags upstream

10. Sync `stable` and `master`

git checkout stable
git merge master # generally, will be a fast-forward merge
git push upstream stable

11. Update GitHub release information using the pushed vX.X.X tag and the appropriate portion of CHANGELOG.md

See the Releases listing on GitHub.

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

1. Update npm version

npm version --no-git-tag-version patch|minor # usually patch

Note: the use of --no-git-tag-version because we want to apply the tag only after we have updated the changelog and see our PR pass in CI.

2. Run tests and build

Note that unlike the "master" branch, the "1.x" branch only offer a "test" script and does not have scripts for formatting and linting. Also note that the build process uses Gulp directly

npm run test
node_modules/.bin/gulp release # or just `gulp release`
git add .
git commit -m "Build Files (auto-generated)"

3. Update CHANGELOG.md

Previously, we used github_changelog_generator to update the changelog but we encountered a number of problems with it in various projects that involve multiple branches.

Until we find a better place for it, the liferay-js-themes-toolkit has a changelog.js script that has no dependencies and which you can use to update the changelog:

node changelog.js --version=$VERSION

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

3. Send release PR to `1.x`

4. Wait to see that all tests pass in CI and then merge

5. Pull `1.x` locally

git pull --ff-only upstream 1.x

6. Publish npm modules and push tags

git tag $VERSION -m $VERSION
npm publish
git push upstream 1.x --follow-tags

7. Sync `1.x-stable` and `1.x`

git checkout 1.x-stable
git merge 1.x # generally, will be a fast-forward merge
git push upstream 1.x-stable

8. Update GitHub release information using the pushed vX.X.X tag and the appropriate portion of CHANGELOG.md