Skip to content

Latest commit

 

History

History
179 lines (117 loc) · 7.09 KB

CONTRIBUTING.md

File metadata and controls

179 lines (117 loc) · 7.09 KB

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, unlikely to be updated).
  • 1.x-stable: points to the latest 1.x release (unlikely to be 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: source files from upstream CKEditor project.
  • 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 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.

Releasing

Collaborators with publish permissions should follow these steps.

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 checkFormat # fix with `npm run format` if necessary
npm run lint:quiet
npm run build
npm run test

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. Generate changelog with github_changelog_generator

gem install github_changelog_generator # using `sudo` if necessary
github_changelog_generator liferay/alloy-editor -t $GITHUB_ACCESS_TOKEN

The $GITHUB_ACCESS_TOKEN can be generated at github.com/settings/tokens/new, and only needs minimal capabilities ("repo:status", "repo_deployment", "public_repo" should suffice).

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

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

Updating CKEditor.

1. Open your favourite browser and navigate to https://ckeditor.com/cke4/builder.

2. On this page you should see a button labelled "Upload build-config.js", click it:

This will open a file dialog letting you choose CKEditor's build configuration file:

This file is located in lib/ckeditor/build-config.js, select it to upload it.

4. Optionally if you want to add more plugins, scroll down and you should see two panels:

On the left you'll see the list of selected plugins (automatically detected by parsing the build-config.js file uploaded previously) and on the right a list of the available plugins. Click on the plugins you wish to add and on the left arrow button ("<"), this will add the new plugins into the "selected plugins" panel.

5. Finally, scroll to the bottom of the page, agree to the terms of use and click the "Download CKEditor" button.

6. Once the file downloaded, unzip it and replace the lib/ckeditor directory with the new directory you unzipped.

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