docs(scripts): add top-level sinopsis #100
Conversation
Seeing as we have our first external "client", I think we should give a high-level intro about what the scripts are for, as well as linking to an example of an integration. Via the "Boy Scout Rule", fixing a capitalization error on the way.
Who's that? Our first "client"? |
https://github.com/liferay/liferay-learn/ via https://github.com/brianchandotcom/liferay-learn/pull/69 |
| `@liferay/npm-scripts` is our principal abstraction for building, formatting, linting, and testing frontend code in [liferay-portal](https://github.com/liferay/liferay-portal). It provides: | ||
|
|
||
| - **A simplified interface:** The `liferay-npm-scripts` command-line implements a small number of subcommands such as `build`, `checkFormat` and `test`, most of which don't require any arguments and do the right thing "out-of-the-box", automatically. | ||
| - **Industry-standard dependencies:** `@liferay/npm-scripts` brings a set of well-tested and robust dependencies including Babel, ESLint, Jest, Prettier, and others, ensuring that people working anywhere in liferay-portal have access to a single, consistent set of tools. |
There was a problem hiding this comment.
We say here working [...] in liferay-portal but below we state to work in a Liferay environment.
I know it's not ready for prime time yet, but maybe the second is better suited as this should grow beyond the liferay-portal repo?
There was a problem hiding this comment.
You got me there. It's still a wee bit aspirational, but changing it wouldn't be egregiously misleading.
| - **Industry-standard dependencies:** `@liferay/npm-scripts` brings a set of well-tested and robust dependencies including Babel, ESLint, Jest, Prettier, and others, ensuring that people working anywhere in liferay-portal have access to a single, consistent set of tools. | ||
| - **Reasonable default configuration:** All of the bundled tools come with configurations that have been tuned to work in a Liferay environment, and can be overridden via standard configuration files (eg. `.eslintrc.js` etc) on the rare occasions that it is necessary to do so. | ||
|
|
||
| While `@liferay/npm-scripts` was designed with liferay-portal in mind, it is also used in other projects such as [liferay-learn](https://github.com/liferay/liferay-learn); see [this issue](https://github.com/liferay/liferay-frontend-projects/issues/91) for context. |
As suggested here: #100 (comment) We eventually want to use liferay-npm-scripst in more places, although at the moment we are only using it in liferay-portal and liferay-learn (and some brave souls have experimented with using it inside workspaces), so we may as well change the language to reflect the direction we're heading in. One less thing to update in the future then.
|
LGTM! Let's always-promise and often-deliver!! |
docs: add general/comments.md (#96)
Seeing as we have our first external "client", I think we should give a high-level intro about what the scripts are for, as well as linking to an example of an integration.
Via the "Boy Scout Rule", fixing a capitalization error on the way.