diff --git a/INFO.md b/INFO.md new file mode 100644 index 0000000..1206589 --- /dev/null +++ b/INFO.md @@ -0,0 +1,27 @@ +If you develop web applications or services running on Node.js, you want to make +sure your code builds and passes tests. This skill will build and test your code +on every push of commits or tags. + +When writing JavaScript, or any one of the numerous languages that transpile +into JavaScript, sooner or later you develop code that you want to use in +multiple projects. The solution is to create and publish an npm package. This +skill is also able to create and publish your code as an npm package to either +the default npm.js registry or your own, private registry. + +This skill supports the follow features: + +- Set up this skill with multiple configurations to run your tests on + different versions of Node.js and npm +- Configure the build to match _your_ desired workflow +- Provide a consistent build configuration across _all_ your projects +- Optionally publish both public and restricted packages to a variety of npm + registries +- Install the custom tools needed for your build and test to complete + successfully +- Create custom npm dist tags +- Cache files from build to build +- Trigger npm builds on pushes of commits and/or tags + +### Build and publish an npm package + +![Build and publish npm package](docs/images/npm-package-publish.png) diff --git a/README.md b/README.md index c6630ce..484ff9b 100644 --- a/README.md +++ b/README.md @@ -1,132 +1,81 @@ # `atomist/npm-build-skill` - +Run NPM scripts to build and optionally publish your JavaScript project. -Run npm scripts to compile or test your JavaScript project +:sparkles: [_**View this skill in the Atomist Skills Catalog**_][atomist-skill] +to enable this skill on your repositories. :sparkles: - +See the [Atomist website][atomist] for general information about Atomist Skills +and the [Atomist documentation site][atomist-doc] for instructions on how to get +started using Atomist Skills. ---- - - - -# What it's useful for - -Run npm scripts with different versions of Node.js and npm in a consistent -container environment. When your tests pass, you can immediately publish the -package to the npmjs.com Registry. - -- Set up this skill with multiple configurations to run your tests on - different versions of Node.js -- Decide to publish your packages consistently from a centralized - configuration -- Own the container environment and install tools needed for your build and - test - -# Before you get started - -Connect and configure this integration: - -- **GitHub** -- **npmjs.com Registry** -- **Slack or Microsoft Teams** - -The **GitHub** integration must be configured in order to use this skill. At -least one repository must be selected. If you want to publish a npm package to -npmjs.com, you need to connect an **npmjs.com Registry**. We recommend that you -configure the **Slack** or **Microsoft Teams** integration. - -# How to configure - -1. **Configure npm scripts to run** - - Provide the name of the npm scripts from the project's `package.json` - scripts section. The order in which the scripts are specified is the order - in which they will get executed. If one script fails, the execution stops. - -1. **Define Node.js version** - - Provide a valid Node.js version or alias as used by - [nvm](https://github.com/nvm-sh/nvm#usage). - -1. **Decide if the package should be published after running the scripts** - - When checked, the skill will run `npm publish` after successful execution of - the configured scripts. - -1. **Define package access** - - `npm publish` allows to publish packages with `public` or `restricted` - access. +[atomist-skill]: + https://go.atomist.com/catalog/skills/atomist/npm-build-skill + "Atomist Skills Catalog - Automate All Your Software Tasks" +[atomist-doc]: https://docs.atomist.com/ "Atomist Documentation" -1. **Create additional npm distribution tags** +## Contributing - Specify additional - [distribution tags](https://docs.npmjs.com/adding-dist-tags-to-packages) - like `next` or `stable` for the published version of the package. +Contributions to this project from community members are encouraged and +appreciated. Please review the [Contributing Guidelines](CONTRIBUTING.md) for +more information. Also see the [Development](#development) section in this +document. -1. **Tag the Git commit on successful execution** +## Code of conduct - Tag the Git commit with the version of the packcage that was just published. +This project is governed by the [Code of Conduct](CODE_OF_CONDUCT.md). You are +expected to act in accordance with this code by participating. Please report any +unacceptable behavior to code-of-conduct@atomist.com. -1. **Specify an optional bash command** +## Connect - In case your npm scripts need different tools - like databases - you can use - this parameter to install such tools. Provide a command that can in a Ubuntu - 20.04 LTS container. +Follow [@atomist][atomist-twitter] on Twitter and [The Atomist +Blog][atomist-blog]. - Here's is an example on how to install MongoDB and start it: +[atomist-twitter]: https://twitter.com/atomist "Atomist on Twitter" +[atomist-blog]: https://blog.atomist.com/ "The Atomist Blog" - ```bash - apt-get update \ - && apt-get install -y wget libcurl4 openssl tar \ - && wget https://fastdl.mongodb.org/linux/mongodb-linux-x86_64-ubuntu1804-4.2.8.tgz \ - && tar -zxvf mongodb-linux-x86_64-ubuntu1804-4.2.8.tgz \ - && cp mongodb-linux-x86_64-ubuntu1804-4.2.8/bin/* /usr/local/bin/ \ - && rm -rf mongodb-linux-x86_64-ubuntu1804-4.2.8* \ - && mkdir -p /var/lib/mongo \ - && mkdir -p /var/log/mongodb \ - && mongod --dbpath /var/lib/mongo --logpath /var/log/mongodb/mongod.log --fork - ``` +## Support -1. **Enable file caching for faster execution times** +General support questions should be discussed in the `#support` channel in the +[Atomist community Slack workspace][slack]. - You can speed up executions times by enabling file caching for certain - artifacts — for example, dependencies — by providing glob patterns of files - you'd like to cache between executions. +If you find a problem, please create an [issue](../../issues). - Note that only files within the `/atm/home` directory can be cached. +## Development - Caching the npm dependency cache could be accomplished with the following - pattern: +You will need to install [Node.js][node] to build and test this project. - `.npm/**` +[node]: https://nodejs.org/ "Node.js" -1. **Determine repository scope** +### Build and test - By default, this skill will be enabled for all repositories in all - organizations you have connected. +Install dependencies. - To restrict the organizations or specific repositories on which the skill - will run, you can explicitly choose organization(s) and repositories. +``` +$ npm ci +``` -# How to build and publish your npm projects +Use the `build` package script to compile, test, lint, and build the +documentation. -1. **Configure at least the npm scripts to run** +``` +$ npm run build +``` -1. **Make some pushes to your configured repositories** +### Release -1. **Enjoy automatic and consistent execution of npm scripts on every push** +Releases are created by pushing a release [semantic version][semver] tag to the +repository, Atomist Skills take care of the rest. -To create feature requests or bug reports, create an -[issue in the repository for this skill](https://github.com/atomist-skills/npm-build-skill/issues). -See the [code](https://github.com/atomist-skills/npm-build-skill) for the skill. +To make this skill globally available, set its maturity to "stable" via the set +maturity drop-down in its Atomist Community Slack channel. - +[semver]: https://semver.org/ "Semantic Version" --- Created by [Atomist][atomist]. Need Help? [Join our Slack workspace][slack]. -[atomist]: https://atomist.com/ "Atomist - How Teams Deliver Software" +[atomist]: https://atomist.com/ "Atomist - Automate All the Software Things" [slack]: https://join.atomist.com/ "Atomist Community Slack" diff --git a/SETTINGS.md b/SETTINGS.md new file mode 100644 index 0000000..07a6f1f --- /dev/null +++ b/SETTINGS.md @@ -0,0 +1,135 @@ +## Before you get started + +Connect and configure these integrations: + +1. [**GitHub**][github] _(required)_ +2. [**npm Registry**][npm] _(optional)_ +3. [**Slack**][slack] or [**Microsoft Teams**][msteams] _(optional)_ + +[github]: https://go.atomist.com/catalog/integration/github "GitHub Integration" +[npm]: + https://go.atomist.com/catalog/integration/npmjs-registry + "npm Registry Integration" +[slack]: https://go.atomist.com/catalog/integration/slack "Slack Integration" +[msteams]: + https://go.atomist.com/catalog/integration/microsoft-teams + "Microsoft Teams Integration" + +## How to configure + +1. **NPM Registry** + + ![npm registry](docs/images/npm-registry.png) + + Select the npm registry from the list of available registries. If you have + not already configured an npm registry, only your GitHub organizations, via + the GitHub Packages npm registry, will appear in the list. + +2. **Triggers** + + ![Event triggers for skill](docs/images/trigger.png) + + Select the events that will trigger execution of the skill. You can select + GitHub pushes, GitHub tags, or both. + +3. **npm scripts to run** + + ![npm scripts to run](docs/images/scripts.png) + + Provide the name of the npm scripts from the project's `package.json` + scripts section. This can be useful if you package needs compiled, tested, + or otherwise transformed before being published. Only provide the name of + the script, not the full `npm run SCRIPT` command. The order in which the + scripts are specified is the order in which they will get executed. If one + script fails, the execution stops. Scripts are run using + `npm run --if-present SCRIPT`, so it is safe to include scripts that are + only present in some of your packages. + +4. **Node.js version** + + ![Node.js version](docs/images/node-version.png) + + Provide a valid Node.js version or alias as used by + [nvm](https://github.com/nvm-sh/nvm#usage), e.g., `12.3.1` or `14`. + +5. **Publish package** + + ![Publish package](docs/images/publish.png) + + When checked, the skill will run `npm publish` after successful execution of + the configured scripts. This will create the package and publish it to the + configured npm registry. If not checked, the package will not be published. + + _You must have an npm registry configured to publish packages._ + +6. **Package access** + + ![Package access](docs/images/access.png) + + `npm publish` allows to publish packages with `public` or `restricted` + access. + +7. **Create additional npm distribution tags** + + ![Package dist tags](docs/images/tags.png) + + Specify additional [distribution tags][dist-tag] like `next` or `stable` for + the published version of the package. In addition to the tags you specify + here, if the skill is running on the default branch, it adds the `next` tag. + Similarly, if the skill is running on a git tag that looks like a release + [semantic version][semver], the `latest` tag is added, making the published + version the new default. + +8. **Specify an optional bash command** + + ![Shell command](docs/images/shell-command.png) + + In case your npm scripts need different tools - like databases - you can use + this parameter to install such tools. Provide a command that can in a Ubuntu + 20.04 LTS container. This command is after the code is checked out but + before Node.js is setup or any npm commands are run. + + Here's is an example on how to install MongoDB and start it: + + ```bash + apt-get update \ + && apt-get install -y wget libcurl4 openssl tar \ + && wget https://fastdl.mongodb.org/linux/mongodb-linux-x86_64-ubuntu1804-4.2.8.tgz \ + && tar -zxvf mongodb-linux-x86_64-ubuntu1804-4.2.8.tgz \ + && cp mongodb-linux-x86_64-ubuntu1804-4.2.8/bin/* /usr/local/bin/ \ + && rm -rf mongodb-linux-x86_64-ubuntu1804-4.2.8* \ + && mkdir -p /var/lib/mongo \ + && mkdir -p /var/log/mongodb \ + && mongod --dbpath /var/lib/mongo --logpath /var/log/mongodb/mongod.log --fork + ``` + +9. **Enable file caching for faster execution times** + + ![Skill file caching](docs/images/cache.png) + + You can speed up executions times by enabling file caching for certain + artifacts — for example, dependencies — by providing glob patterns of files + you'd like to cache between executions. + + Note that only files within the `/atm/home` directory can be cached. + + Caching the npm dependency cache could be accomplished with the pattern + `.npm/**/*`. + +10. **Determine repository scope** + + ![Repository filter](docs/images/repo-filter.png) + + By default, this skill will be enabled for all repositories in all + organizations you have connected. + + To restrict the organizations or specific repositories on which the skill + will run, you can explicitly choose organization(s) and repositories. + +11. **Activate the skill** + + Save your configuration and activate the skill by clicking the "Enable + skill" button. + +[dist-tag]: https://docs.npmjs.com/adding-dist-tags-to-packages "npm dist-tags" +[semver]: https://semver.org/ "Semantic Versioning" diff --git a/docs/images/access.png b/docs/images/access.png new file mode 100644 index 0000000..03aea9a Binary files /dev/null and b/docs/images/access.png differ diff --git a/docs/images/cache.png b/docs/images/cache.png new file mode 100644 index 0000000..33f2e5c Binary files /dev/null and b/docs/images/cache.png differ diff --git a/docs/images/node-version.png b/docs/images/node-version.png new file mode 100644 index 0000000..71a2cc5 Binary files /dev/null and b/docs/images/node-version.png differ diff --git a/docs/images/npm-package-publish.png b/docs/images/npm-package-publish.png new file mode 100644 index 0000000..23048c0 Binary files /dev/null and b/docs/images/npm-package-publish.png differ diff --git a/docs/images/npm-registry.png b/docs/images/npm-registry.png new file mode 100644 index 0000000..c476668 Binary files /dev/null and b/docs/images/npm-registry.png differ diff --git a/docs/images/publish.png b/docs/images/publish.png new file mode 100644 index 0000000..11bf416 Binary files /dev/null and b/docs/images/publish.png differ diff --git a/docs/images/repo-filter.png b/docs/images/repo-filter.png new file mode 100644 index 0000000..08bc6bf Binary files /dev/null and b/docs/images/repo-filter.png differ diff --git a/docs/images/scripts.png b/docs/images/scripts.png new file mode 100644 index 0000000..2bbffa7 Binary files /dev/null and b/docs/images/scripts.png differ diff --git a/docs/images/shell-command.png b/docs/images/shell-command.png new file mode 100644 index 0000000..b189a6a Binary files /dev/null and b/docs/images/shell-command.png differ diff --git a/docs/images/tags.png b/docs/images/tags.png new file mode 100644 index 0000000..dd06359 Binary files /dev/null and b/docs/images/tags.png differ diff --git a/docs/images/trigger.png b/docs/images/trigger.png new file mode 100644 index 0000000..b677712 Binary files /dev/null and b/docs/images/trigger.png differ diff --git a/skill.ts b/skill.ts index df1e2bb..f9f508c 100644 --- a/skill.ts +++ b/skill.ts @@ -27,6 +27,7 @@ import { Configuration } from "./lib/configuration"; export const Skill = skill< Configuration & { repos: any; subscription_filter: any } >({ + description: "Run npm scripts to compile or test your JavaScript project", displayName: "npm Build", categories: [Category.DevOps],