Skip to content

Contributing

Jump to bottom
Greg Hurrell edited this page Aug 2, 2019 · 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

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/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

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.

Things to check 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.

0. Update the master branch

git checkout master
git pull upstream master

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

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 package.json version

yarn 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.md and package.json

git commit -p -m "Prepare for vX.X.X release"

6. Send release PR to stable 

git push upstream master

You can now create a draft PR (proposing a merge of "master" into "stable"); we won't actually merge this PR; we just want to see the CI pass.

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

Once we've seen the CI pass above, we can close the PR without merging it (it was already pushed to the "master" branch) and publish our tags.

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

git checkout stable
git pull upstream stable
git merge --ff-only master
git tag $VERSION -m $VERSION
npm publish --dry-run # Final sanity check.
yarn publish
git push --follow-tags upstream

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

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.

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

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, close the PR and the push directly.

git push upstream 1.x
git co 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 "1.x" tag.

yarn publish --tag 1.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