diff --git a/.atlassian/OWNER b/.atlassian/OWNER new file mode 100644 index 00000000..962dccf7 --- /dev/null +++ b/.atlassian/OWNER @@ -0,0 +1 @@ +mkemp diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 00000000..ce3a9d1d --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,27 @@ +# Contributor Code of Conduct + +As contributors and maintainers of this project, and in the interest of fostering an open and welcoming community, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities. + +We are committed to making participation in this project a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, religion, or nationality. + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery +* Personal attacks +* Trolling or insulting/derogatory comments +* Public or private harassment +* Publishing other's private information, such as physical or electronic addresses, without explicit permission +* Submitting contributions or comments that you know to violate the intellectual property or privacy rights of others +* Other unethical or unprofessional conduct + +Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful. +By adopting this Code of Conduct, project maintainers commit themselves to fairly and consistently applying these principles to every aspect of managing this project. Project maintainers who do not follow or enforce the Code of Conduct may be permanently removed from the project team. + +This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. + +Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting a project maintainer. Complaints will result in a response and be reviewed and investigated in a way that is deemed necessary and appropriate to the circumstances. Maintainers are obligated to maintain confidentiality with regard to the reporter of an incident. + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.3.0, available at [http://contributor-covenant.org/version/1/3/0/][version] + +[homepage]: http://contributor-covenant.org +[version]: http://contributor-covenant.org/version/1/3/0/ diff --git a/FORK_CHANGELOG.md b/FORK_CHANGELOG.md new file mode 100644 index 00000000..18261338 --- /dev/null +++ b/FORK_CHANGELOG.md @@ -0,0 +1,9 @@ +# Changelog + +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). + +## [Unreleased] + +[unreleased]: https://github.com/olivierlacan/keep-a-changelog/compare/v1.1.1...HEAD diff --git a/README.md b/README.md index 51cfba12..f7d1bf2a 100644 --- a/README.md +++ b/README.md @@ -1,583 +1,55 @@ -# frontend-maven-plugin +# Atlassian fork of "frontend-maven-plugin" -[![Build Status OSX and Linux](https://travis-ci.org/eirslett/frontend-maven-plugin.png?branch=master)](https://travis-ci.org/eirslett/frontend-maven-plugin) -[![Build status Windows](https://ci.appveyor.com/api/projects/status/vxbccc1t9ceadhi9?svg=true)](https://ci.appveyor.com/project/eirslett/frontend-maven-plugin) -[![Maven Central](https://maven-badges.herokuapp.com/maven-central/com.github.eirslett/frontend-maven-plugin/badge.svg?style=flat)](https://maven-badges.herokuapp.com/maven-central/com.github.eirslett/frontend-maven-plugin/) +[![license](https://img.shields.io/badge/license-Apache%202.0-blue.svg?style=flat-square)](LICENSE) ![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square) -This plugin downloads/installs Node and NPM locally for your project, runs `npm install`, and then any combination of -[Bower](http://bower.io/), [Grunt](http://gruntjs.com/), [Gulp](http://gulpjs.com/), [Jspm](http://jspm.io), -[Karma](http://karma-runner.github.io/), or [Webpack](http://webpack.github.io/). -It's supposed to work on Windows, OS X and Linux. +## Intro -If you prefer [Yarn](https://yarnpkg.com/) over [NPM](https://www.npmjs.com/) for your node package fetching, -this plugin can also download Node and Yarn and then run `yarn install` for your project. +First read the upstream [README](https://github.com/eirslett/frontend-maven-plugin) -#### What is this plugin meant to do? -- Let you keep your frontend and backend builds as separate as possible, by -reducing the amount of interaction between them to the bare minimum; using only 1 plugin. -- Let you use Node.js and its libraries in your build process without installing Node/NPM -globally for your build system -- Let you ensure that the version of Node and NPM being run is the same in every build environment +## Purpose -#### What is this plugin not meant to do? -- Not meant to replace the developer version of Node - frontend developers will still install Node on their -laptops, but backend developers can run a clean build without even installing Node on their computer. -- Not meant to install Node for production uses. The Node usage is intended as part of a frontend build, -running common javascript tasks such as minification, obfuscation, compression, packaging, testing etc. +There are a few changes that are not wanted upstream, but are useful to developing for Atlassian products -**Notice:** _This plugin does not support already installed Node or npm versions. Use the `exec-maven-plugin` instead._ +## Goals -## Requirements +* Make it as easy as possible to use without subverting expectations +* Keep in sync with upstream +* Upstream as much as possible -* _Maven 3.6_ and _Java 1.8_ -* For _Maven 2_ support take a look at the [wiki](https://github.com/eirslett/frontend-maven-plugin/wiki#maven-2). - -## Installation - -Include the plugin as a dependency in your Maven project. Change `LATEST_VERSION` to the latest tagged version. - -```xml - - - com.github.eirslett - frontend-maven-plugin - - LATEST_VERSION - ... - -... -``` - -## Usage - -Have a look at the [example project](frontend-maven-plugin/src/it/example%20project), -to see how it should be set up: https://github.com/eirslett/frontend-maven-plugin/blob/master/frontend-maven-plugin/src/it/example%20project/pom.xml - - - [Installing node and npm](#installing-node-and-npm) - - [Installing node and yarn](#installing-node-and-yarn) - - Running - - [npm](#running-npm) - - [yarn](#running-yarn) - - [bower](#running-bower) - - [grunt](#running-grunt) - - [gulp](#running-gulp) - - [jspm](#running-jspm) - - [karma](#running-karma) - - [webpack](#running-webpack) - - Configuration - - [Working Directory](#working-directory) - - [Installation Directory](#installation-directory) - - [Proxy Settings](#proxy-settings) - - [Environment variables](#environment-variables) - - [Ignoring Failure](#ignoring-failure) - - [Skipping Execution](#skipping-execution) - -**Recommendation:** _Try to run all your tasks via npm scripts instead of running bower, grunt, gulp etc. directly._ - -### Installing node and npm - -The versions of Node and npm are downloaded from https://nodejs.org/dist, extracted and put into a `node` folder created -in your [installation directory](#installation-directory) . Node/npm will only be "installed" locally to your project. -It will not be installed globally on the whole system (and it will not interfere with any Node/npm installations already -present). - -```xml - - ... - - - - install node and npm - - install-node-and-npm - - - generate-resources - - - - v4.6.0 - - - 2.15.9 - - - http://myproxy.example.org/nodejs/ - - -``` - -You can also specify separate download roots for npm and node as they are stored in separate repos. In case the root configured requires authentication, you can specify a server ID from your maven settings file: - -```xml - - ... - - - http://myproxy.example.org/nodejs/ - - server001 - - https://myproxy.example.org/npm/ - - -``` - -You can use Nexus repository Manager to proxy npm registries. See https://help.sonatype.com/display/NXRM3/Npm+Registry - -**Notice:** _Remember to gitignore the `node` folder, unless you actually want to commit it._ - -### Installing node and yarn - -Instead of using Node with npm you can alternatively choose to install Node with Yarn as the package manager. - -The versions of Node and Yarn are downloaded from `https://nodejs.org/dist` for Node -and from the Github releases for Yarn, -extracted and put into a `node` folder created in your installation directory. -Node/Yarn will only be "installed" locally to your project. -It will not be installed globally on the whole system (and it will not interfere with any Node/Yarn installations already -present). - -If your project is using Yarn Berry (2.x or above), the Yarn version is handled per project but a Yarn 1.x install is still needed as a "bootstrap". -The plugin will try to detect `.yarnrc.yml` file in the current Maven project/module folder, at the root of the multi-module project if relevant, and in the folder from which the `mvn` command was run. -If detected, the plugin will assume your project is using Yarn Berry. It will install the 1.x Yarn version you specify with `yarnVersion` as bootstrap, then hand over to your project-specific version. - -Have a look at the example `POM` to see how it should be set up with Yarn: -https://github.com/eirslett/frontend-maven-plugin/blob/master/frontend-maven-plugin/src/it/yarn-integration/pom.xml - - -```xml - - ... - - - install node and yarn - - install-node-and-yarn - - - generate-resources - - - v6.9.1 - v0.16.1 - - - http://myproxy.example.org/nodejs/ - - http://myproxy.example.org/yarn/ - - -``` - -### Running npm - -All node packaged modules will be installed in the `node_modules` folder in your [working directory](#working-directory). -By default, colors will be shown in the log. - -```xml - - npm install - - npm - - - - generate-resources - - - - install - - -``` - -**Notice:** _Remember to gitignore the `node_modules` folder, unless you actually want to commit it. Npm packages will -always be installed in `node_modules` next to your `package.json`, which is default npm behavior._ - -#### npx - -You can also use [`npx` command](https://blog.npmjs.org/post/162869356040/introducing-npx-an-npm-package-runner), enabling you to execute the CLI of installed packages without a run-script, or even packages that aren't installed at all. - -```xml - - say hello - - npx - - - generate-resources - - - cowsay hello - - -``` - -### Running yarn - -As with npm above, all node packaged modules will be installed in the `node_modules` folder in your [working directory](#working-directory). - -```xml - - yarn install - - yarn - - - - install - - -``` - -#### Yarn with Private Registry - -NOTE: if you have a private npm registry that mirrors the npm registry, be aware that yarn.lock -includes URLs to the npmjs.org module registry and yarn install will use these paths when installing modules. - -If you want yarn.lock to use your private npm registry, be sure to run these commands on your local machine before you generate yarn.lock: -``` -yarn config set registry -yarn install -``` -This will create URLs in your yarn.lock file that reference your private npm registry. - -Another way to set a registry is to add a .npmrc file in your project's root directory that contains: -``` -registry= -``` - -Also you can set a registry using a tag `npmRegistryURL` -``` - - yarn install - - yarn - - - - install - - http://myregistry.example.org/ - - -``` - -### Running bower - -All bower dependencies will be installed in the `bower_components` folder in your working directory. - -```xml - - bower install - - bower - - - - - install - - -``` - -**Notice:** _Remember to gitignore the `bower_components` folder, unless you actually want to commit it._ - -### Running Grunt - -It will run Grunt according to the `Gruntfile.js` in your working directory. -By default, colors will be shown in the log. - -```xml - - grunt build - - grunt - - - - generate-resources - - - - build - - -``` - -### Running gulp - -Very similar to the Grunt execution. It will run gulp according to the `gulpfile.js` in your working directory. -By default, colors will be shown in the log. - -```xml - - gulp build - - gulp - - - - generate-resources - - - - build - - -``` - -### Running jspm - -All jspm dependencies will be installed in the `jspm_packages` folder in your working directory. - -```xml - - jspm install - - jspm - - - - - install - - -``` - -### Running Karma - -```xml - - javascript tests - - karma - - - - test - - - - src/test/javascript/karma.conf.ci.js - - -``` - -**Skipping tests:** If you run maven with the `-DskipTests` flag, karma tests will be skipped. - -**Ignoring failed tests:** If you want to ignore test failures run maven with the `-Dmaven.test.failure.ignore` flag, -karma test results will not stop the build but test results will remain -in test output files. Suitable for continuous integration tool builds. - -**Why karma.conf.ci.js?** When using Karma, you should have two separate -configurations: `karma.conf.js` and `karma.conf.ci.js`. (The second one should inherit configuration -from the first one, and override some options. The example project shows you how to set it up.) -The idea is that you use `karma.conf.js` while developing (using watch/livereload etc.), and -`karma.conf.ci.js` when building - for example, when building, it should only run karma once, -it should generate xml reports, it should run only in PhantomJS, and/or it should generate -code coverage reports. - -**Running Karma through Grunt or gulp:** You may choose to run Karma [directly through Grunt](https://github.com/karma-runner/grunt-karma) -or [through gulp](https://github.com/karma-runner/gulp-karma) instead, as part of the `grunt` or `gulp` execution. That -will help to separate your frontend and backend builds even more. - -### Running Webpack - -```xml - - webpack build - - webpack - - - - generate-resources - - - - -p - - -``` - -### Optional Configuration - -#### Working directory - -The working directory is where you've put `package.json` and your frontend configuration files (`Gruntfile.js` or -`gulpfile.js` etc). The default working directory is your project's base directory (the same directory as your `pom.xml`). -You can change the working directory if you want: - -```xml - - com.github.eirslett - frontend-maven-plugin - - - - src/main/frontend - - -``` - -**Notice:** _Npm packages will always be installed in `node_modules` next to your `package.json`, which is default npm behavior._ - -#### Installation Directory - -The installation directory is the folder where your node and npm are installed. -You can set this property on the different goals. Or choose to set it for all the goals, in the maven configuration. - -```xml - - com.github.eirslett - frontend-maven-plugin - - - - target - - -``` - -#### Proxy settings - -If you have [configured proxy settings for Maven](http://maven.apache.org/guides/mini/guide-proxies.html) -in your settings.xml file, the plugin will automatically use the proxy for downloading node and npm, as well -as [passing the proxy to npm commands](https://docs.npmjs.com/misc/config#proxy). - -**Non Proxy Hosts:** npm does not currently support non proxy hosts - if you are using a proxy and npm install -is not downloading from your repository, it may be because it cannot be accessed through your proxy. -If that is the case, you can stop the npm execution from inheriting the Maven proxy settings like this: - -```xml - - false - -``` - -If you have [configured proxy settings for Maven](http://maven.apache.org/guides/mini/guide-proxies.html) -in your settings.xml file, the plugin will automatically [pass the proxy to bower commands](https://docs.npmjs.com/misc/config#proxy). -If that is the case, you can stop the bower execution from inheriting the Maven proxy settings like this: - -```xml - - false - -``` - -If you want to disable proxy for Yarn you can use `yarnInheritsProxyConfigFromMaven`. When you have proxy settings in your settings.xml file if you don't use this param it will run code below with proxy settings, in some cases you don't want that. Adding this param into the configuration section will solve this issue - -```xml - - tests - - yarn - - compile - - false - run test - - - -``` - - -#### Environment variables - -If you need to pass some variable to Node, you can set that using the property `environmentVariables` in configuration -tag of an execution like this: - -```xml - - - - Snow - Lannister - - - ${NODE_ENV} - - -``` - -#### Ignoring Failure - -**Ignoring failed tests:** If you want to ignore test failures in specific execution you can set that using the property `maven.test.failure.ignore` in configuration tag of an execution like this: - -```xml - - true - -``` +## Issues, Contributing -#### Skipping Execution +Thank you for considering a contribution! Pull requests, issues and comments are welcome. -Each frontend build tool and package manager allows skipping execution. -This is useful for projects that contain multiple builds (such as a module containing Java and frontend code). +Please try to contribute upstream first. It maximises the value out of every change and keeps this fork easier to maintain. You can check [upstream's issue tracker](https://github.com/eirslett/frontend-maven-plugin/issues) and [pull requests](https://github.com/eirslett/frontend-maven-plugin/pulls) to gauge maintainer opinion and avoid duplicate work. -**Note** that if the package manager (npm or yarn) is skipped, other build tools will also need to be skipped because they -would not have been downloaded. -For example, in a project using npm and gulp, if npm is skipped, gulp must also be skipped or the build will fail. +Please minimise changes to the upstream code to keep syncing with upstream easy. -Tools and property to enable skipping +For pull requests, please: -* npm `-Dskip.npm` -* yarn `-Dskip.yarn` -* bower `-Dskip.bower` -* bun `-Dskip.bun` -* grunt `-Dskip.grunt` -* gulp `-Dskip.gulp` -* jspm `-Dskip.jspm` -* karma `-Dskip.karma` -* webpack `-Dskip.webpack` +* Add tests for new features and bug fixes +* Follow the existing style +* Separate unrelated changes into multiple pull requests -## Eclipse M2E support +See the existing issues for things to start contributing. -This plugin contains support for M2E, including lifecycle mappings and support for incremental builds in Eclipse. -The `install-node-and-npm` goal will only run on a full project build. The other goals support incremental builds -to avoid doing unnecessary work. During an incremental build the `npm` goal will only run if the `package.json` file -has been changed. The `grunt` and `gulp` goals have new `srcdir` and `triggerfiles` optional configuration options; if -these are set they check for changes in your source files before being run. See the wiki for more information. +For bigger changes, please make sure you start a discussion first by creating an issue and explaining the intended change. -## Helper scripts +Atlassian requires contributors to sign a Contributor License Agreement, known as a CLA. This serves as a record stating that the contributor is entitled to contribute the code/documentation/translation to the project and is willing to have it used in distributions and derivative works (or is willing to transfer ownership). -During development, it's convenient to have the "npm", "bower", "grunt", "gulp" and "karma" commands -available on the command line. If you want that, use [those helper scripts](frontend-maven-plugin/src/it/example%20project/helper-scripts)! +Prior to accepting your contributions we ask that you please follow the appropriate link below to digitally sign the CLA. The Corporate CLA is for those who are contributing as a member of an organization and the individual CLA is for those contributing as an individual. -## To build this project: +* [CLA for corporate contributors](https://opensource.atlassian.com/corporate) +* [CLA for individuals](https://opensource.atlassian.com/individual) -Run `$ mvn clean install` +### Releasing -## Issues, Contributing +Only Atlassians may release a new version, [follow this guide](https://hello.atlassian.net/wiki/spaces/~278062200/pages/1407390489/HOW+TO+Do+a+manual+maven+artifact+release). -Please post any issues on the [Github's Issue tracker](https://github.com/eirslett/frontend-maven-plugin/issues). -[Pull requests](https://github.com/eirslett/frontend-maven-plugin/pulls) are welcome! -You can find a full list of [contributors here](https://github.com/eirslett/frontend-maven-plugin/graphs/contributors). +## Usage requirements -## License +* Java 8, until support is dropped from all DC products ([currently projected for 2026-04-19](https://hello.atlassian.net/wiki/spaces/DCCore/pages/3989804253/When+can+I+stop+supporting+Java+8+11+entirely+in+DC)) +* Maven 3.6 (because of upstream) -[Apache 2.0](LICENSE) +## Usage guidance +[![Cheers from Atlassian](https://raw.githubusercontent.com/atlassian-internal/oss-assets/master/banner-cheers-light.png)](https://www.atlassian.com)