Merge branch 'master' into feature/insert (documentcloud#199)

.github/workflows/cd.yml

@@ -0,0 +1,71 @@
+# This workflow is like CI, but also builds the documentation and deploys to NPM
+# and gh-pages.
+
+name: Continuous Deployment
+
+on:
+  push:
+    branches: [prepublish]
+  workflow_run:
+    workflows: [Prepublication staging]
+    types: [completed]
+
+jobs:
+  deploy:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v2
+      with:
+        ref: prepublish
+    - name: Use Node.js 14.x
+      uses: actions/setup-node@v1
+      with:
+        node-version: 14.x
+    - name: Configure yarn cache path
+      run: yarn config set cache-folder ~/.yarn-cache
+    - name: Restore yarn cache
+      uses: actions/cache@v2
+      with:
+        path: ~/.yarn-cache
+        key: yarn-cache-14.x
+        restore-keys: |
+          yarn-cache-
+    - name: Restore node_modules
+      uses: actions/cache@v2
+      with:
+        path: node_modules
+        key: node-modules-14.x-${{ hashFiles('yarn.lock') }}
+        restore-keys: |
+          node-modules-14.x-
+          node-modules-
+    - name: Install dependencies
+      run: yarn
+    - name: Build dist files and docs and run the tests
+      run: yarn grunt dist docco tocdoc
+    - name: Commit the build output
+      uses: EndBug/add-and-commit@v5
+      with:
+        add: dist/ index.html
+        message: Autocommit build output (continuous deployment)
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+    - name: Publish to NPM
+      run: yarn publish
+      env:
+        NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+    - name: Merge into gh-pages
+      uses: devmasx/[email protected]
+      with:
+        type: now
+        target_branch: gh-pages
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+    - uses: actions/checkout@v2
+      with:
+        ref: gh-pages
+    - name: Tag the release
+      uses: Klemensas/action-autotag@stable
+      with:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        tag_prefix: v

.github/workflows/ci.yml

@@ -0,0 +1,46 @@
+# This workflow will install the node_modules, build the source code and run tests across different versions of node
+# For more information see: https://help.github.com/actions/language-and-framework-guides/using-nodejs-with-github-actions
+
+name: Continuous Integration
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [10.x, 14.x]
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Use Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@v1
+      with:
+        node-version: ${{ matrix.node-version }}
+    - name: Configure yarn cache path
+      run: yarn config set cache-folder ~/.yarn-cache
+    - name: Restore yarn cache
+      uses: actions/cache@v2
+      with:
+        path: ~/.yarn-cache
+        key: yarn-cache-${{ matrix.node-version }}
+        restore-keys: |
+          yarn-cache-
+    - name: Restore node_modules
+      uses: actions/cache@v2
+      with:
+        path: node_modules
+        key: node-modules-${{ matrix.node-version }}-${{ hashFiles('yarn.lock') }}
+        restore-keys: |
+          node-modules-${{ matrix.node-version }}-
+          node-modules-
+    - name: Install dependencies
+      run: yarn
+    - name: Run linter, concat, minifier and tests
+      run: yarn dist

.github/workflows/prepublish.yml

@@ -0,0 +1,26 @@
+# As an alternative to a manual push to the prepublish branch, this workflow can
+# be triggered on a release branch by assigning a special label to its pull
+# request in order to set the CD circus in motion.
+
+name: Prepublication staging
+
+on:
+  pull_request:
+    types: [labeled]
+    # Would filter by branch here, but GH Actions wrongly decides not to
+    # trigger the workflow if we do this.
+
+jobs:
+  stage:
+    runs-on: ubuntu-latest
+    # Filtering by branch here instead. Credit due to @MiguelSavignano.
+    # https://github.com/devmasx/merge-branch/issues/11
+    if: contains(github.event.pull_request.head.ref, 'release/') || contains(github.event.pull_request.head.ref, 'hotfix/')
+    steps:
+      - uses: actions/checkout@v2
+      - name: Merge into prepublish
+        uses: devmasx/[email protected]
+        with:
+          label_name: ready to launch
+          target_branch: prepublish
+          github_token: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -8,3 +8,5 @@ examples/*.css
 examples/*.html
 examples/public
 bower_components/*
+dist/
+/index.html

CONTRIBUTING.md

@@ -10,28 +10,29 @@ Create your own fork of contrib where you can make your changes.
 
 ## 3. Install development dependencies
 
-Make sure you have [Node.js][node] and the [grunt cli][cli] installed. Then install contrib's development dependencies with `npm install`.
+Make sure you have [Node.js][node] and [Yarn][yarn] installed. Then install contrib's development dependencies with `yarn`. Note that these dependencies include the [Grunt CLI][cli] which we use for task automation.
 
 ## 4. Change the code
 
 Make your code changes, ensuring they adhere to the same [coding style as Underscore][style]. Do **not** edit the files in `dist/`.
 
-Make any necessary updates to the qUnit tests found in `test/`. Run `grunt test` to catch any test failures or lint issues. You can also use `grunt watch:test` to get instant feedback each time you save a file.
+Make any necessary updates to the qUnit tests found in `test/`. Run `yarn test` to catch any test failures or lint issues. You can also use `yarn grunt watch:test` to get instant feedback each time you save a file.
 
 ## 5. Update the docs
 
 Make any necessary documentation updates in `docs/`. Do **not** edit `index.html` directly.
 
-After updating the docs, run `grunt tocdoc` to rebuild the `index.html` file. Visually inspect `index.html` in your browser to ensure the generated docs look nice.
+After updating the docs, run `yarn tocdoc` to rebuild the `index.html` file. Visually inspect `index.html` in your browser to ensure the generated docs look nice.
 
 ## 6. Send a pull request
 
 Send a pull request to `documentcloud/underscore-contrib` for feedback.
 
-If modifications are necessary, make the changes and rerun `grunt test` or `grunt tocdoc` as needed.
+If modifications are necessary, make the changes and rerun `yarn test` or `yarn tocdoc` as needed.
 
 And hopefully your pull request will be merged by the core team! :-)
 
 [style]:https://github.com/documentcloud/underscore/blob/master/underscore.js
 [node]:http://nodejs.org/
-[cli]:http://gruntjs.com/getting-started#installing-the-cli
+[yarn]:https://classic.yarnpkg.com/
+[cli]:http://gruntjs.com/getting-started#installing-the-cli

DEPLOYING.md

@@ -0,0 +1,49 @@
+# How to cut a new release for Underscore-contrib
+
+This is a checklist for repository maintainers. It covers all the steps involved in releasing a new version, including publishing to NPM and updating the `gh-pages` branch. We have tried to automate as many of these steps as possible using GitHub Actions. The workflows involved are in the (hidden) `.github` directory.
+
+A "regular" release includes new changes that were introduced to the `master` branch since the previous release. A *hotfix* release instead skips any such changes and only addresses urgent problems with the previous release.
+
+
+## Steps
+
+1. Ensure your local `master` branch descends from the previous release branch and that it is in a state that you want to release. **Exception:** for hotfixes, ensure you have an up-to-date local copy of the previous release branch instead.
+2. Decide on the next version number, respecting [semver][semver]. For the sake of example we'll use `1.2.3` as a placeholder version throughout this checklist.
+3. Create a `release/1.2.3` branch based on `master`. **Exception:** if this is a hotfix, start from the previous release branch instead and call it `hotfix/1.2.3`.
+4. Bump the version number in the `package.json` and the `yarn.lock` by running the command `yarn version --no-git-tag-version`, with the extra flag `--major`, `--minor` or `--patch` depending on which part of the version number you're incrementing (e.g., `--patch` if you're bumping from 1.2.2 to 1.2.3). Note that you can configure `yarn` to always include the `--no-git-tag-version` flag so you don't have to type it every time.
+5. Bump the version number in the source code and in `docs/index.md` accordingly.
+6. Commit the changes from steps 4 and 5 with a commit message of the format `Bump the version to 1.2.3`.
+7. Add more commits to extend the change log and to update any other documentation that might require it. Ensure that all documentation looks good.
+8. Push the release branch and create a pull request against `master` (also if it is a hotfix).
+9. At your option, have the release branch reviewed and add more commits to satisfy any change requests.
+10. The "Continuous Integration" workflow will trigger automatically on the pull request. This runs the test suite against multiple environments. Wait for all checks to complete.
+11. If any checks fail, add more commits to fix and repeat from step 10.
+12. When all reviewers are satisfied and all checks pass, apply the "ready to launch" label to the pull request. This will trigger the "Prepublication staging" workflow, which will merge the release branch into the `prepublish` branch. Merge manually if the workflow fails for whatever reason. **Note:** do *not* merge into `master` yet.
+13. The merging of new changes into `prepublish` will trigger the "Continuous Deployment" workflow, which is documented below. **Pay attention as the deployment workflow progresses.**
+14. If the deployment workflow fails, identify the failing step and address as quickly as possible. Possible solution steps include:
+    - Adding new commits to the release branch and repeating from step 12 (most likely if the docs fail to build for some reason).
+    - Manually pushing new commits to the `prepublish` branch and repeating from step 13 (this might be needed in case of merge conflicts, although this is highly unlikely).
+    - Manually running `yarn publish` (if something is wrong with the NPM registry or the authentication credentials).
+    - Manually merging `prepublish` into `gh-pages` (in unlikely case of merge conflicts).
+    - Manually tagging the release on `gh-pages`.
+15. When the deployment workflow has completed, double-check that the new version was published to NPM, that the website was updated and that the repository contains a tag for the new release.
+16. Finally merge the release branch into `master`, but keep the branch around for a few days in case you need to do a hotfix.
+17. Delete the release branch. You can still restore it if necessary, by tracing the history graph two commits back from the release tag.
+
+
+## Automated continuous deployment workflow
+
+This workflow is defined in `.github/workflows/cd.yml`. Note that roughly the first half of the steps in that file consists of basic boilerplate to check out the source and install dependencies.
+
+The publishing to NPM depends on a [secret][secrets] named `NPM_TOKEN`, representing the API token of the NPM account that owns the `underscore-contrib` package. Only admins of the documentcloud organization can access this setting.
+
+1. Checkout the source, restore caches and install the dependencies.
+2. Run `yarn grunt dist docco tocdoc`.
+3. Commit the output of the previous step to the `prepublish` branch.
+4. Publish to NPM.
+5. Merge the `prepublish` branch into `gh-pages`.
+6. Tag the tip of `gh-pages` with the version number in the `package.json`.
+
+
+[semver]: https://semver.org
+[secrets]: https://docs.github.com/en/free-pro-team@latest/actions/reference/encrypted-secrets

Gruntfile.js

@@ -88,8 +88,8 @@ module.exports = function(grunt) {
     }
   });
 
-  grunt.registerTask("test", ["jshint", "qunit:main"]);
-  grunt.registerTask("dist", ["concat", "uglify"]);
+  grunt.registerTask('test', ['jshint', 'qunit:main']);
   grunt.registerTask('default', ['test']);
   grunt.registerTask('dist', ['test', 'concat', 'qunit:concat', 'uglify', 'qunit:min']);
+  grunt.registerTask('doc', ['test', 'tocdoc']);
 };