Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Massive overhaul of CONTRIBUTING.md #1099

Merged
merged 3 commits into from
Feb 13, 2019
Merged

Massive overhaul of CONTRIBUTING.md #1099

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
0e4257f
Soft-wrap CONTRIBUTING.md
wincent Feb 12, 2019
5031a83
Massive overhaul of CONTRIBUTING.md
wincent Feb 13, 2019
896d14f
Replace `gulp release` reference with `npm run build`
wincent Feb 13, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
145 changes: 79 additions & 66 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,45 +1,53 @@
# 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.
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

TBD
### 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](https://github.com/liferay/alloy-editor/tree/master/dist): target directory where bundles (alloy-editor-all.js and friends) are built.
* [lib/ckeditor](https://github.com/liferay/alloy-editor/tree/master/lib/ckeditor): source files from upstream CKEditor project.
* [lib/lang](https://github.com/liferay/alloy-editor/tree/master/lib/lang): language strings from upstream CKEditor project.
* [src/adapter/main.js](https://github.com/liferay/alloy-editor/tree/master/src/adapter/main.js): defines the top-level `AlloyEditor` API.
* [src/assets/lang](https://github.com/liferay/alloy-editor/tree/master/src/assets/lang): defines AlloyEditor-specific strings.
* [src/components](https://github.com/liferay/alloy-editor/tree/master/src/components): React components for buttons and toolbars.
* [src/lang](https://github.com/liferay/alloy-editor/tree/master/src/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](https://github.com/liferay/alloy-editor/tree/master/src/plugins): CKEditor plugins for resizing, aligning, and so on.
* [test](https://github.com/liferay/alloy-editor/tree/master/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.
* 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:
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.
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:
Additionally, you can also run the test suite via Saucelabs with the following npm script:

```
npm testSaucelabs
Expand All @@ -59,42 +67,42 @@ All methods should be documented, following [Google's format](https://github.com

Collaborators with publish permissions should follow these steps.

There are two different workflows for publishing this project, one for scheduled
releases, and one for emergency hot fixes.

## Scheduled release

1. Create a release branch from the updated `master` branch
## 0. Update the `master` branch

```
git checkout master
git pull upstream master
git checkout -b release/vX.X.X
```

2. Send release PR to `master`

3. Wait to see that all tests pass and then merge with merge commit

4. Checkout and pull `master` locally
## 1. Run formatting, lint, build, and tests locally as a sanity check

```
git checkout master && git pull upstream master
npm run checkFormat # fix with `npm run format` if necessary
npm run lint:quiet
npm run build
npm run test
```

5. Update npm version
## 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:

```
npm version patch|minor|major
git branch 2.x
git branch 2.x-stable
git push upstream 2.x
git push upstream 2.x-stable
```

6. Build the dist files
## 3. Update npm version

```
npm run build
npm version --no-git-tag-version patch|minor|major
```

7. Generate changelog with [github_changelog_generator](https://github.com/skywinder/github-changelog-generator)
**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](https://github.com/skywinder/github-changelog-generator)

```
gem install github_changelog_generator # using `sudo` if necessary
Expand All @@ -103,63 +111,68 @@ github_changelog_generator liferay/alloy-editor -t $GITHUB_ACCESS_TOKEN

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

8. Commit changelog
## 5. Commit changelog

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

9. Publish npm modules and push release tags
## 6. Send release PR to `master`

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

## 8. Pull `master` locally

```
npm publish --dry-run # Final sanity check.
npm publish
git push --follow-tags
git pull --ff-only upstream master
```


10. Sync `master` with `stable`
## 6. Rebuild the dist files

```
git checkout master
git merge stable
npm run build
```

11. Do GitHub release using the pushed vX.X.X tag and the appropriate portion of
CHANGELOG.md
## 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:

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

1. Create a feature branch from `stable` (assuming hot fix has already been
merged)
## 10. Sync `stable` and `master`

```
git checkout stable
git pull upstream stable
git checkout -b feature/fix_foo
git merge master # generally, will be a fast-forward merge
git push upstream stable
```

2. Send a fix PR to `stable`
## 11. Update GitHub release information using the pushed vX.X.X tag and the appropriate portion of CHANGELOG.md

3. Follow steps 3-11 of a scheduled release
See [the Releases listing](https://github.com/liferay/alloy-editor/releases) on GitHub.

## Updating CKEditor.

1. Open your favourite browser and navigate to https://ckeditor.com/cke4/builder.
### 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*:
### 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 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.
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:
### 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.
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.
### 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.
### 6. Once the file downloaded, unzip it and *replace* the `lib/ckeditor` directory with the new directory you unzipped.

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