Tooling: Ensure consistent formatting in all scripts #30795
Comments
gziolo
added
Needs Dev
|
👋 What would be some instructions to reproduce the issue? Doing
# Managing Packages
This repository uses lerna to manage WordPress modules and publish them as packages to npm. Creating a New PackageWhen creating a new package, you need to provide at least the following:
Managing DependenciesThere are two types of dependencies that you might want to add to one of the existing WordPress packages. Production DependenciesProduction dependencies are stored in the Adding New DependenciesThe simplest way to add a production dependency to one of the packages is to run a very convenient lerna add command from the root of the project. Example: lerna add lodash packages/a11yThis command adds the latest version of Removing Existing DependenciesRemoving a dependency from one of the WordPress packages requires some manual work. You need to remove the line in the corresponding Example: +++ b/packages/scripts/package.json
@@ -43,7 +43,6 @@
"check-node-version": "^4.1.0",
"cross-spawn": "^5.1.0",
"eslint": "^7.1.0",
- "jest": "^26.6.3",
"minimist": "^1.2.0",
"npm-package-json-lint": "^3.6.0",Next, you need to run Updating Existing DependenciesThis is the most confusing part of working with lerna which causes a lot of hassles for contributors. The most successful strategy so far is to do the following:
Development DependenciesIn contrast to production dependencies, development dependencies shouldn't be stored in individual WordPress packages. Instead they should be installed in the project's Example: npm install glob --save-devThis commands adds the latest version of Maintaining API documentationEach public API change needs to be reflected in the corresponding API documentation. To ensure that code and documentation are in sync automatically, Gutenberg has developed a few utilities. Packages can add the following HTML comment within their top-level <!-- START TOKEN(Autogenerated API docs) -->
Content within the HTML comment will be replaced by the generated documentation.
<!-- END TOKEN(Autogenerated API docs) -->`.Each time there is a commit to the public API of the package the The above snippet within the package's Packages may want to use a different source file or add the exports of many files into the same <!-- START TOKEN(Autogenerated API docs|src/actions.js) -->
Content within the HTML comment will be replaced by the generated documentation.
<!-- END TOKEN(Autogenerated API docs|src/actions.js) -->`.Maintaining ChangelogsIn maintaining dozens of npm packages, it can be tough to keep track of changes. To simplify the release process, each package includes a For each pull request, you should always include relevant changes in a "Unreleased" heading at the top of the file. You should add the heading if it doesn't already exist. Example: <!-- Learn how to maintain this file at https://github.com/WordPress/gutenberg/tree/HEAD/packages#maintaining-changelogs. -->
## Unreleased
### Bug Fix
- Fixed an off-by-one error with the `sum` function.There are a number of common release subsections you can follow. Each is intended to align to a specific meaning in the context of the Semantic Versioning (
While other section naming can be used when appropriate, it's important that are expressed clearly to avoid confusion for both the packages releaser and third-party consumers. When in doubt, refer to Semantic Versioning specification. If you are publishing new versions of packages, note that there are versioning recommendations outlined in the Gutenberg Release Process document which prescribe minimum version bumps for specific types of releases. The chosen version should be the greater of the two between the semantic versioning and Gutenberg release minimum version bumps. Releasing PackagesLerna automatically releases all outdated packages. To check which packages are outdated and will be released, type If you have the ability to publish packages, you must have 2FA enabled on your npm account. Before ReleasingConfirm that you're logged in to npm, by running If you're publishing a new package, ensure that its {
"publishConfig": {
"access": "public"
}
}You can check your package configs by running Development ReleaseRun the following commands from the npm install
./bin/plugin/cli.js npm-nextSee more details in Development Releases section of the Gutenberg release process documentation. Production ReleaseTo release a production version for the outdated packages, run the following commands from the npm install
./bin/plugin/cli.js npm-latestSee more details in Synchronizing WordPress Trunk section of the Gutenberg release process documentation. Legacy Patch ReleaseTo release a patch for the older major or minor version of packages, run the following commands from the corresponding npm install
npm run publish:patchThis is usually necessary when adding bug fixes or security patches to the earlier versions of WordPress. This will publish only a patch version of the built packages. This is useful for backpublishing certain packages to WordPress. See more details in Minor WordPress Releases section of the Gutenberg release process documentation. TypeScriptThe TypeScript language is a typed superset of JavaScript that compiles to plain JavaScript. Gutenberg uses TypeScript for several reasons, including:
Using TypeScriptGutenberg uses TypeScript by running the TypeScript compiler ( To opt-in to TypeScript tooling, packages should include a A {
// Extends a base configuration common to most packages
"extends": "../../tsconfig.base.json",
// Options for the TypeScript compiler
// We'll usually set our `rootDir` and `declarationDir` as follows, which is specific
// to each project.
"compilerOptions": {
"rootDir": "src",
"declarationDir": "build-types"
},
// Which source files should be included
"include": [ "src/**/*" ],
// Other WordPress package dependencies that have opted-in to TypeScript should be listed
// here. In this case, our package depends on `@wordpress/dom-ready`.
"references": [ { "path": "../dom-ready" } ]
}Type declarations will be produced in the {
"main": "build/index.js",
"main-module": "build-module/index.js",
"types": "build-types"
}Ensure that the Optimizing for bundlersIn order for bundlers to tree-shake packages effectively, they often need to know whether a package includes side effects in its code. This is done through the If your package has no side effects, simply set the field to {
"name": "package",
"sideEffects": false
}If your package includes a few files with side effects, you can list them instead: {
"name": "package",
"sideEffects": [
"file-with-side-effects.js",
"another-file-with-side-effects.js"
]
}Please consult the side effects documentation for more information on identifying and declaring side effects. Side effectsWhat are side effects?Many Here is an example: import { registerStore } from '@wordpress/data';
const store = registerStore( STORE_NAME, {
// ...
} );
However, if this were to happen inside of an import { registerStore } from '@wordpress/data';
export function init() {
const store = registerStore( STORE_NAME, {
// ...
} );
}
// `init` doesn't get called at the top level of the module,
// therefore importing the module doesn't cause side effects.Declaring a variable or performing any modification at the top level that only affects the current module isn't a side effect either, since it's contained to the module: import list from './list';
// Not a side effect.
let localVariable = [];
// Not a side effect, either.
for ( const entry of list ) {
localVariable.push( processListEntry( entry ) );
}The influence of side effects on bundlingModern bundlers have the concept of tree-shaking, where unused code is removed from the final bundles, as it's not necessary. This becomes important in libraries that offer a lot of different functionality, since consumers of that library may only be using a small portion of it, and don't want their bundles to be larger than necessary. These libraries should thus take steps to ensure they can indeed be correctly tree-shaken, and This brings us back to side effects. As we've seen, side effects are code that runs simply by virtue of importing a module, and has an external influence of some sort. This means that the code cannot be tree-shaken away; it needs to run, because it changes things outside of the module that may be needed elsewhere. Unfortunately, side effects are hard to determine automatically, and some bundlers err on the side of caution, assuming that every module potentially has side effects. This becomes a problem for // index.js
export { a, b } from './module1';
export { c, d, e } from './module2';
export { f } from './module3';
// Nothing can be tree-shaken away, because the bundler doesn't know if
// this or the re-exported modules have any side effects.Telling bundlers about side effectsSince bundlers can't figure out side effects for themselves, we need to explicitly declare them. That's done in a package's {
"name": "package",
"sideEffects": false
}If it has a few files with side effects, it can list them: {
"name": "package",
"sideEffects": [ "dist/store/index.js", "dist/polyfill/index.js" ]
}This allows the bundler to assume that only the modules that were declared have side effects, and nothing else does. Of course, this means that we need to be careful to include everything that does have side effects, or problems can arise in applications that make use of the package. StorybookStorybook is an open-source tool that provides a sandbox to develop and visualize components in isolation. See the Storybook site for more information about the tool. The Gutenberg project uses Storybook to view and work with the UI components developed in the WordPress packages. View online at: https://wordpress.github.io/gutenberg/ Run locally in your development environment running: |
|
It should be |
|
Ok, took a look at this, my braindump:
Does this help? |
|
Thank you @nosolosw. It looks like we can collect updated files and run Prettier on all of them in one call or individually after each file gets updated 👍🏻 |
What problem does this address?
Follow-up for #30714.
Follow-up for #30715.
What is your proposed solution?
It looks like
npm run fixtures:regeneratecommand conflicts with whatnpx prettier --write **/*.jsondoes for all JSON files. We should updatenpm run fixtures:regenerateto produce output that is aligned with Prettier formatting.npx prettier --write **/*.mddoesn't play nicely withnpm run docs:build. We should update@wordpress/docgento align both.The text was updated successfully, but these errors were encountered: