diff --git a/.eslintignore b/.eslintignore index 9a603c2bceb3d4..9c169f96f35883 100644 --- a/.eslintignore +++ b/.eslintignore @@ -7,5 +7,4 @@ packages/block-serialization-spec-parser/parser.js packages/e2e-tests/plugins packages/react-native-editor/bundle vendor -wordpress !.*.js diff --git a/.eslintrc.js b/.eslintrc.js index 6d841c60444bed..b78d72bde774c7 100644 --- a/.eslintrc.js +++ b/.eslintrc.js @@ -2,6 +2,8 @@ * External dependencies */ const { escapeRegExp } = require( 'lodash' ); +const glob = require( 'glob' ).sync; +const { join } = require( 'path' ); /** * Internal dependencies @@ -28,13 +30,17 @@ const developmentFiles = [ '**/@(storybook|stories)/**/*.js', ]; +// All files from packages that have types provided with TypeScript. +const typedFiles = glob( 'packages/*/package.json' ) + .filter( ( fileName ) => require( join( __dirname, fileName ) ).types ) + .map( ( fileName ) => fileName.replace( 'package.json', '**/*.js' ) ); + module.exports = { root: true, extends: [ 'plugin:@wordpress/eslint-plugin/recommended', 'plugin:eslint-comments/recommended', ], - plugins: [ 'import' ], globals: { wp: 'off', }, @@ -54,6 +60,38 @@ module.exports = { allowedTextDomain: 'default', }, ], + '@wordpress/no-unsafe-wp-apis': 'off', + '@wordpress/data-no-store-string-literals': 'warn', + 'import/default': 'error', + 'import/named': 'error', + 'no-restricted-imports': [ + 'error', + { + paths: [ + { + name: 'lodash', + importNames: [ 'memoize' ], + message: 'Please use `memize` instead.', + }, + { + name: 'react', + message: + 'Please use React API through `@wordpress/element` instead.', + }, + { + name: 'reakit', + message: + 'Please use Reakit API through `@wordpress/components` instead.', + }, + { + name: 'redux', + importNames: [ 'combineReducers' ], + message: + 'Please use `combineReducers` from `@wordpress/data` instead.', + }, + ], + }, + ], 'no-restricted-syntax': [ 'error', // NOTE: We can't include the forward slash in our regex or @@ -81,17 +119,13 @@ module.exports = { }, { selector: - 'ImportDeclaration[source.value="redux"] Identifier.imported[name="combineReducers"]', - message: 'Use `combineReducers` from `@wordpress/data`', - }, - { - selector: - 'ImportDeclaration[source.value="lodash"] Identifier.imported[name="memoize"]', - message: 'Use memize instead of Lodash’s memoize', + 'CallExpression[callee.object.name="page"][callee.property.name="waitFor"]', + message: + 'This method is deprecated. You should use the more explicit API methods available.', }, { selector: - 'CallExpression[callee.object.name="page"][callee.property.name="waitFor"]', + 'CallExpression[callee.object.name="page"][callee.property.name="waitForTimeout"]', message: 'Prefer page.waitForSelector instead.', }, { @@ -121,21 +155,14 @@ module.exports = { 'Avoid truthy checks on length property rendering, as zero length is rendered verbatim.', }, ], - // Temporarily converted to warning until all errors are resolved. - // See https://github.com/WordPress/gutenberg/pull/22771 for the eslint-plugin-jsdoc update. - 'jsdoc/check-param-names': 'warn', - 'jsdoc/require-param': 'warn', }, overrides: [ { - files: [ 'packages/**/*.js' ], - excludedFiles: [ - '**/*.@(android|ios|native).js', - ...developmentFiles, - ], + files: [ '**/*.@(android|ios|native).js', ...developmentFiles ], rules: { - 'import/no-extraneous-dependencies': 'error', - 'import/no-unresolved': 'error', + 'import/no-extraneous-dependencies': 'off', + 'import/no-unresolved': 'off', + 'import/named': 'off', }, }, { @@ -183,5 +210,12 @@ module.exports = { 'no-console': 'off', }, }, + { + files: typedFiles, + rules: { + 'jsdoc/no-undefined-types': 'off', + 'jsdoc/valid-types': 'off', + }, + }, ], }; diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 033ecb9d331c06..cfdf8c8890f3e3 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -11,19 +11,19 @@ /packages/data-controls @nerrad # Blocks -/packages/block-library @ajitbohra @talldan +/packages/block-library @ajitbohra /packages/block-library/src/gallery @mkevins /packages/block-library/src/social-links @mkaz /packages/block-library/src/social-link @mkaz /packages/block-library/src/image @ajlende # Editor -/packages/annotations @atimmer @ellatrix +/packages/annotations @atimmer /packages/autop /packages/block-editor @ellatrix /packages/block-serialization-spec-parser @dmsnell /packages/block-serialization-default-parser @dmsnell -/packages/blocks @ellatrix +/packages/blocks /packages/edit-post /packages/editor /packages/list-reusable-blocks @@ -46,20 +46,21 @@ /bin @ntwb @nerrad @ajitbohra /bin/api-docs @ntwb @nerrad @ajitbohra @nosolosw /docs/tool @chrisvanpatten @ajitbohra @nosolosw -/packages/babel-plugin-import-jsx-pragma @gziolo @ntwb @nerrad @ajitbohra +/packages/babel-plugin-import-jsx-pragma @ntwb @nerrad @ajitbohra /packages/babel-plugin-makepot @ntwb @nerrad @ajitbohra /packages/babel-preset-default @gziolo @ntwb @nerrad @ajitbohra -/packages/browserslist-config @gziolo @ntwb @nerrad @ajitbohra +/packages/browserslist-config @ntwb @nerrad @ajitbohra /packages/create-block @gziolo @mkaz +/packages/create-block-tutorial-template @gziolo /packages/custom-templated-path-webpack-plugin @ntwb @nerrad @ajitbohra /packages/docgen @nosolosw -/packages/e2e-test-utils @gziolo @ntwb @nerrad @ajitbohra -/packages/e2e-tests @ntwb @nerrad @ajitbohra @talldan +/packages/e2e-test-utils @ntwb @nerrad @ajitbohra +/packages/e2e-tests @ntwb @nerrad @ajitbohra /packages/eslint-plugin @gziolo @ntwb @nerrad @ajitbohra /packages/jest-console @gziolo @ntwb @nerrad @ajitbohra /packages/jest-preset-default @gziolo @ntwb @nerrad @ajitbohra /packages/jest-puppeteer-axe @gziolo @ntwb @nerrad @ajitbohra -/packages/library-export-default-webpack-plugin @gziolo @ntwb @nerrad @ajitbohra +/packages/library-export-default-webpack-plugin @ntwb @nerrad @ajitbohra /packages/npm-package-json-lint-config @gziolo @ntwb @nerrad @ajitbohra /packages/postcss-themes @ntwb @nerrad @ajitbohra /packages/scripts @gziolo @ntwb @nerrad @ajitbohra @@ -88,16 +89,16 @@ /packages/html-entities /packages/i18n @swissspidy /packages/is-shallow-equal -/packages/keycodes @talldan @ellatrix +/packages/keycodes /packages/priority-queue /packages/token-list -/packages/url @talldan +/packages/url /packages/wordcount /packages/warning /packages/keyboard-shortcuts # Extensibility -/packages/hooks @gziolo @adamsilverstein +/packages/hooks @adamsilverstein /packages/plugins @gziolo @adamsilverstein # Rich Text @@ -106,7 +107,7 @@ /packages/block-editor/src/components/rich-text @ellatrix @cameronvoell @guarani # Project Management -/.github @mapk @karmatosed +/.github /packages/project-management-automation # wp-env @@ -116,6 +117,9 @@ /lib @timothybjacobs @spacedmonkey /lib/global-styles.php @timothybjabocs @spacedmonkey @nosolosw /lib/experimental-default-theme.json @timothybjabocs @spacedmonkey @nosolosw +/lib/class-wp-theme-json.php @timothybjabocs @spacedmonkey @nosolosw +/lib/class-wp-theme-json-resolver.php @timothybjabocs @spacedmonkey @nosolosw +/phpunit/class-wp-theme-json-test.php @nosolosw # Native (Unowned) *.native.js @ghost diff --git a/.github/ISSUE_TEMPLATE/Bug_report.md b/.github/ISSUE_TEMPLATE/Bug_report.md index 050d91e2ef0015..a27a295da50896 100644 --- a/.github/ISSUE_TEMPLATE/Bug_report.md +++ b/.github/ISSUE_TEMPLATE/Bug_report.md @@ -1,40 +1,68 @@ --- name: Bug report -about: Create a report to help us improve +about: Report a bug with the WordPress block editor or Gutenberg plugin --- -**Describe the bug** -A clear and concise description of what the bug is. + + +## Description + + +## Step-by-step reproduction instructions + + +## Expected behaviour + + +## Actual behaviour + + +## Screenshots or screen recording (optional) + + +## Code snippet (optional) + + +## WordPress information +- WordPress version: +- Gutenberg version: +- Are all plugins except Gutenberg deactivated? +- Are you using a default theme (e.g. Twenty Twenty-One)? + +## Device information +- Device: +- Operating system: +- Browser: diff --git a/.github/ISSUE_TEMPLATE/Bug_report_mobile.md b/.github/ISSUE_TEMPLATE/Bug_report_mobile.md new file mode 100644 index 00000000000000..06b6fad1bb6bc3 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/Bug_report_mobile.md @@ -0,0 +1,55 @@ +--- +name: Bug report (Mobile) +about: Report a bug with the mobile app version of Gutenberg +labels: Mobile App - i.e. Android or iOS + +--- + + + +## Description + + +## Step-by-step reproduction instructions + + +## Expected behaviour + + +## Actual behaviour + + +## Screenshots or screen recording (optional) + + +## WordPress information +- WordPress version: +- Gutenberg version: +- Are all plugins except Gutenberg deactivated? +- Are you using a default theme (e.g. Twenty Twenty-One)? + +## Device information +- Device: +- Operating system: +- WordPress app version: diff --git a/.github/ISSUE_TEMPLATE/Custom.md b/.github/ISSUE_TEMPLATE/Custom.md deleted file mode 100644 index c621fa8402fc45..00000000000000 --- a/.github/ISSUE_TEMPLATE/Custom.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -name: Help Request -about: Please post help requests or ‘how to’ questions in support channels first - ---- - -Search first! Your issue may have already been reported. - -For general help requests, please post in the support forum at https://wordpress.org/support/forum/how-to-and-troubleshooting/. - -Technical help requests have their own section of the support forum at https://wordpress.org/support/forum/wp-advanced/. - -You may also ask for technical support at https://wordpress.stackexchange.com/. - -Please make sure you have checked the Handbook at https://wordpress.org/gutenberg/handbook before asking your question. - -Thank you! diff --git a/.github/ISSUE_TEMPLATE/Feature_request.md b/.github/ISSUE_TEMPLATE/Feature_request.md index e36eff9baf5d2b..cfae99f42ff9ea 100644 --- a/.github/ISSUE_TEMPLATE/Feature_request.md +++ b/.github/ISSUE_TEMPLATE/Feature_request.md @@ -1,14 +1,18 @@ --- name: Feature request -about: Suggest an idea for this project +about: Propose an idea for a feature or an enhancement --- -**Is your feature request related to a problem? Please describe.** -A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] +## What problem does this address? + -**Describe the solution you'd like** -A clear and concise description of what you want to happen. - -**Describe alternatives you've considered** -A clear and concise description of any alternative solutions or features you've considered. +## What is your proposed solution? + diff --git a/.github/ISSUE_TEMPLATE/Mobile_apps_bug_report.md b/.github/ISSUE_TEMPLATE/Mobile_apps_bug_report.md deleted file mode 100644 index 8581315fe6c8ab..00000000000000 --- a/.github/ISSUE_TEMPLATE/Mobile_apps_bug_report.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -name: Bug report for Mobile Apps -about: Create a report to help us improve the Gutenberg mobile apps version -labels: Mobile App Android/iOS ---- - -**Describe the bug** -A clear and concise description of what the bug is. - -**To reproduce** -Steps to reproduce the behavior: -1. Go to '...' -2. Tap on '....' -3. Scroll down to '....' -4. See '... exact error ...' - -**Expected behavior** -A clear and concise description of what you expected to happen. - -**Screenshots** -If applicable, add screenshots to help explain your problem. - -**Editor version (please complete the following information):** -- WordPress version: [e.g: 5.3.2] -- Does the website have the Gutenberg plugin installed, or is it using the block editor that comes by default? [e.g: "gutenberg plugin", "default"] -- If the Gutenberg plugin is installed, which version is it? [e.g., 7.6] - -**Smartphone (please complete the following information):** - - Device: [e.g. iPhone6, Pixel 3] - - OS: [e.g. iOS 8.1, Android 10.0] - - WordPress App Version [e.g. 15.3] or Demo App Version [branch name or git commit hash] - -**Additional context** -- To report a security issue, please visit the WordPress HackerOne program: https://hackerone.com/wordpress. diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 00000000000000..d30612c4f194ff --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,11 @@ +blank_issues_enabled: true +contact_links: + - name: General help request + url: https://wordpress.org/support/forum/how-to-and-troubleshooting/ + about: For general help requests, create a new topic in the Fixing WordPress support forum + - name: Technical help request + url: https://wordpress.org/support/forum/wp-advanced/ + about: For more technical help requests, create a new topic in the Developing with WordPress Forum + - name: Development help request + url: https://wordpress.stackexchange.com/ + about: For questions about WordPress development, ask a question in the WordPress Development Stack Exchange diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 94e2bce07afc13..744aed32a11e0d 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,4 +1,4 @@ - + ## Description @@ -20,6 +20,7 @@ - [ ] My code is tested. - [ ] My code follows the WordPress code style. - [ ] My code follows the accessibility standards. +- [ ] I've tested my changes with keyboard and screen readers. - [ ] My code has proper inline documentation. - [ ] I've included developer documentation if appropriate. -- [ ] I've updated all React Native files affected by any refactorings/renamings in this PR. +- [ ] I've updated all React Native files affected by any refactorings/renamings in this PR. diff --git a/.github/SUPPORT.md b/.github/SUPPORT.md index e813100a83a9a5..02165e02a7f955 100644 --- a/.github/SUPPORT.md +++ b/.github/SUPPORT.md @@ -3,9 +3,9 @@ Welcome to Gutenberg, a WordPress project. We hope you join us in creating the future platform for publishing; all are welcome here. -* Please see the [Contributing Guidelines](https://github.com/WordPress/gutenberg/blob/master/CONTRIBUTING.md) for additional information on how to contribute. +* Please see the [Contributing Guidelines](https://github.com/WordPress/gutenberg/blob/HEAD/CONTRIBUTING.md) for additional information on how to contribute. -* As with all WordPress projects, we want to ensure a welcoming environment for everyone. With that in mind, all contributors are expected to follow our [Code of Conduct](https://github.com/WordPress/gutenberg/blob/master/CODE_OF_CONDUCT.md). +* As with all WordPress projects, we want to ensure a welcoming environment for everyone. With that in mind, all contributors are expected to follow our [Code of Conduct](https://github.com/WordPress/gutenberg/blob/HEAD/CODE_OF_CONDUCT.md). * Join us on Slack for real-time communication, it is where maintainers coordinate around the project. To get started using Slack, see: https://make.wordpress.org/chat/ diff --git a/.github/workflows/build-plugin-zip.yml b/.github/workflows/build-plugin-zip.yml index 52218898bed0d8..7b4c161ff3b5e5 100644 --- a/.github/workflows/build-plugin-zip.yml +++ b/.github/workflows/build-plugin-zip.yml @@ -5,7 +5,7 @@ on: paths-ignore: - '**.md' push: - branches: [master] + branches: [trunk] tags: - 'v*' paths-ignore: @@ -17,10 +17,10 @@ jobs: runs-on: ubuntu-latest steps: - name: Checkout code - uses: actions/checkout@master + uses: actions/checkout@5a4ac9002d0be2fb38bd78e4b4dbde5606d7042f # v2.3.4 - name: Cache node modules - uses: actions/cache@v2 + uses: actions/cache@26968a09c0ea4f3e233fdddbafd1166051a095f6 # v2.1.4 env: cache-name: cache-node-modules with: @@ -32,10 +32,10 @@ jobs: ${{ runner.os }}-build- ${{ runner.os }}- - - name: Use Node.js 12.x - uses: actions/setup-node@v1 + - name: Use Node.js 14.x + uses: actions/setup-node@46071b5c7a2e0c34e49c3cb8a0e792e86e18d5ea # v2.1.5 with: - node-version: 12.x + node-version: 14.x - name: Build Gutenberg plugin ZIP file run: ./bin/build-plugin-zip.sh @@ -43,7 +43,51 @@ jobs: NO_CHECKS: 'true' - name: Upload artifact - uses: actions/upload-artifact@v2 + uses: actions/upload-artifact@e448a9b857ee2131e752b06002bf0e093c65e571 # v2.2.2 with: name: gutenberg-plugin - path: ./gutenberg.zip \ No newline at end of file + path: ./gutenberg.zip + + create-release: + name: Create Release Draft and Attach Asset + needs: build + runs-on: ubuntu-latest + if: startsWith(github.ref, 'refs/tags/v') + steps: + - name: Set Release Version + id: get_release_version + run: echo ::set-output name=version::$(echo $GITHUB_REF | cut -d / -f 3 | sed s/^v// | sed 's/-rc./ RC/' ) + + - name: Download Plugin Zip Artifact + uses: actions/download-artifact@4a7a711286f30c025902c28b541c10e147a9b843 # v2.0.8 + with: + name: gutenberg-plugin + + - name: Extract Changelog for Release + run: | + unzip gutenberg.zip changelog.txt + CHANGELOG_REGEX="/=\s[0-9]+\.[0-9]+\.[0-9]+(-rc\.[0-9]+)?\s=/" + awk -i inplace "$CHANGELOG_REGEX"'{p++;next} p==2{exit} p>=1' changelog.txt + + - name: Create Release Draft + id: create_release + uses: actions/create-release@0cb9c9b65d5d1901c1f53e5e66eaf4afd303e70e # v1.1.4 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + with: + tag_name: ${{ github.ref }} + release_name: ${{ steps.get_release_version.outputs.version }} + draft: true + prerelease: ${{ contains(github.ref, 'rc') }} + body_path: changelog.txt + + - name: Upload Release Asset + id: upload-release-asset + uses: actions/upload-release-asset@e8f9f06c4b078e705bd2ea027f0926603fc9b4d5 # v1.0.2 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + with: + upload_url: ${{ steps.create_release.outputs.upload_url }} + asset_path: ./gutenberg.zip + asset_name: gutenberg.zip + asset_content_type: application/zip diff --git a/.github/workflows/bundle-size.yml b/.github/workflows/bundle-size.yml index e1e6c292fd24df..1b85fa623e23fe 100644 --- a/.github/workflows/bundle-size.yml +++ b/.github/workflows/bundle-size.yml @@ -8,11 +8,11 @@ jobs: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@5a4ac9002d0be2fb38bd78e4b4dbde5606d7042f # v2.3.4 with: fetch-depth: 1 - - uses: preactjs/compressed-size-action@v2 + - uses: preactjs/compressed-size-action@7d87f60a6b0c7d193b8183ce859ed00b356ea92f # v2.1.0 with: repo-token: "${{ secrets.GITHUB_TOKEN }}" pattern: "{build/**/*.js,build/**/*.css}" diff --git a/.github/workflows/cancel.yml b/.github/workflows/cancel.yml index e65d084e10d840..6c8cc20fe1135f 100644 --- a/.github/workflows/cancel.yml +++ b/.github/workflows/cancel.yml @@ -9,7 +9,7 @@ jobs: - name: Get all workflow ids and set to env variable run: echo "WORKFLOW_IDS_TO_CANCEL=$(curl https://api.github.com/repos/${GITHUB_REPOSITORY}/actions/workflows -s | jq -r '.workflows | map(.id|tostring) | join(",")')" >> $GITHUB_ENV - - uses: styfle/cancel-workflow-action@0.4.0 + - uses: styfle/cancel-workflow-action@3d86a7cc43670094ac248017207be0295edbc31d # v0.8.0 with: workflow_id: ${{ env.WORKFLOW_IDS_TO_CANCEL }} access_token: ${{ secrets.GITHUB_TOKEN }} diff --git a/.github/workflows/create-block.yml b/.github/workflows/create-block.yml index 65a39db4936932..4bff464420313d 100644 --- a/.github/workflows/create-block.yml +++ b/.github/workflows/create-block.yml @@ -7,22 +7,26 @@ on: - '!packages/**/test/**' - '!packages/**/*.md' push: - branches: [master] + branches: [trunk, wp/trunk] paths: - 'packages/**' - '!packages/**/test/**' - '!packages/**/*.md' jobs: - build: - + checks: + name: Checks runs-on: ubuntu-latest + strategy: + fail-fast: false + matrix: + node: [12, 14] steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@5a4ac9002d0be2fb38bd78e4b4dbde5606d7042f # v2.3.4 - name: Cache node modules - uses: actions/cache@v2 + uses: actions/cache@26968a09c0ea4f3e233fdddbafd1166051a095f6 # v2.1.4 env: cache-name: cache-node-modules with: @@ -34,14 +38,12 @@ jobs: ${{ runner.os }}-build- ${{ runner.os }}- - - name: Use Node.js 14.x - uses: actions/setup-node@v1 + - name: Use Node.js ${{ matrix.node }}.x + uses: actions/setup-node@46071b5c7a2e0c34e49c3cb8a0e792e86e18d5ea # v2.1.5 with: - node-version: 14.x + node-version: ${{ matrix.node }} - name: npm install, build, format and lint run: | npm ci npm run test:create-block - env: - CI: true diff --git a/.github/workflows/end2end-test.yml b/.github/workflows/end2end-test.yml index a42371f5e13692..dc10ffe7a12ab8 100644 --- a/.github/workflows/end2end-test.yml +++ b/.github/workflows/end2end-test.yml @@ -5,7 +5,9 @@ on: paths-ignore: - '**.md' push: - branches: [master] + branches: + - trunk + - 'wp/**' paths-ignore: - '**.md' @@ -22,10 +24,10 @@ jobs: steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@5a4ac9002d0be2fb38bd78e4b4dbde5606d7042f # v2.3.4 - name: Cache node modules - uses: actions/cache@v2 + uses: actions/cache@26968a09c0ea4f3e233fdddbafd1166051a095f6 # v2.1.4 env: cache-name: cache-node-modules with: @@ -38,7 +40,7 @@ jobs: ${{ runner.os }}- - name: Use Node.js 14.x - uses: actions/setup-node@v1 + uses: actions/setup-node@46071b5c7a2e0c34e49c3cb8a0e792e86e18d5ea # v2.1.5 with: node-version: 14.x @@ -58,7 +60,7 @@ jobs: $( npm bin )/wp-scripts test-e2e --config=./packages/e2e-tests/jest.config.js --cacheDirectory="$HOME/.jest-cache" --runTestsByPath $( awk 'NR % 4 == ${{ matrix.part }} - 1' < ~/.jest-e2e-tests ) - name: Archive debug artifacts (screenshots, HTML snapshots) - uses: actions/upload-artifact@v2 + uses: actions/upload-artifact@e448a9b857ee2131e752b06002bf0e093c65e571 # v2.2.2 if: always() with: name: failures-artifacts diff --git a/.github/workflows/performance.yml b/.github/workflows/performance.yml index 1c6be548c7a519..857bed9849def8 100644 --- a/.github/workflows/performance.yml +++ b/.github/workflows/performance.yml @@ -4,18 +4,20 @@ on: pull_request: paths-ignore: - '**.md' + release: + types: [created] jobs: performance: - name: Compare performance with master + name: Run performance tests runs-on: ubuntu-latest steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@5a4ac9002d0be2fb38bd78e4b4dbde5606d7042f # v2.3.4 - name: Cache node modules - uses: actions/cache@v2 + uses: actions/cache@26968a09c0ea4f3e233fdddbafd1166051a095f6 # v2.1.4 env: cache-name: cache-node-modules with: @@ -28,7 +30,7 @@ jobs: ${{ runner.os }}- - name: Use Node.js 14.x - uses: actions/setup-node@v1 + uses: actions/setup-node@46071b5c7a2e0c34e49c3cb8a0e792e86e18d5ea # v2.1.5 with: node-version: 14.x @@ -36,5 +38,23 @@ jobs: run: | npm ci - - name: Run the performance tests - run: ./bin/plugin/cli.js perf --ci $GITHUB_SHA master --tests-branch $GITHUB_SHA + - name: Compare performance with trunk + if: github.event_name == 'pull_request' + run: ./bin/plugin/cli.js perf --ci $GITHUB_SHA trunk --tests-branch $GITHUB_SHA + + - name: Compare performance with current WordPress Core and previous Gutenberg versions + if: github.event_name == 'release' + env: + PLUGIN_VERSION: ${{ github.event.release.name }} + run: | + IFS='.' read -r -a PLUGIN_VERSION_ARRAY <<< "$PLUGIN_VERSION" + CURRENT_RELEASE_BRANCH="release/${PLUGIN_VERSION_ARRAY[0]}.${PLUGIN_VERSION_ARRAY[1]}" + PREVIOUS_VERSION_BASE_10=$(expr ${PLUGIN_VERSION_ARRAY[0]} \* 10 + ${PLUGIN_VERSION_ARRAY[1]} - 1) + PREVIOUS_RELEASE_BRANCH="release/$(expr $PREVIOUS_VERSION_BASE_10 / 10).$(expr $PREVIOUS_VERSION_BASE_10 % 10)" + TESTED_UP_TO_REGEX="Tested up to: \K([0-9]+)\.([0-9]+)\.?([0-9]?)" + WP_VERSION=$(grep -oP "$TESTED_UP_TO_REGEX" ./readme.txt) + IFS='.' read -r -a WP_VERSION_ARRAY <<< "$WP_VERSION" + WP_BRANCH="wp/${WP_VERSION_ARRAY[0]}.${WP_VERSION_ARRAY[1]}" + ./bin/plugin/cli.js perf --ci $WP_BRANCH $PREVIOUS_RELEASE_BRANCH $CURRENT_RELEASE_BRANCH + + diff --git a/.github/workflows/pull-request-automation.yml b/.github/workflows/pull-request-automation.yml index 96117582cc408e..b3fe89023d2bf3 100644 --- a/.github/workflows/pull-request-automation.yml +++ b/.github/workflows/pull-request-automation.yml @@ -9,10 +9,10 @@ jobs: runs-on: ubuntu-latest steps: # Checkout defaults to using the branch which triggered the event, which - # isn't necessarily `master` (e.g. in the case of a merge). - - uses: actions/checkout@v2 + # isn't necessarily `trunk` (e.g. in the case of a merge). + - uses: actions/checkout@5a4ac9002d0be2fb38bd78e4b4dbde5606d7042f # v2.3.4 with: - ref: master + ref: trunk # Changing into the action's directory and running `npm install` is much # faster than a full project-wide `npm ci`. diff --git a/.github/workflows/rnmobile-android-runner.yml b/.github/workflows/rnmobile-android-runner.yml index b88529ebb16eaa..aa1156da286d07 100644 --- a/.github/workflows/rnmobile-android-runner.yml +++ b/.github/workflows/rnmobile-android-runner.yml @@ -5,7 +5,7 @@ on: paths-ignore: - '**.md' push: - branches: [master] + branches: [trunk] paths-ignore: - '**.md' @@ -20,10 +20,10 @@ jobs: steps: - name: checkout - uses: actions/checkout@v2 + uses: actions/checkout@5a4ac9002d0be2fb38bd78e4b4dbde5606d7042f # v2.3.4 - name: Restore npm cache - uses: actions/cache@v2 + uses: actions/cache@26968a09c0ea4f3e233fdddbafd1166051a095f6 # v2.1.4 with: path: ~/.npm key: ${{ runner.os }}-npm-${{ hashFiles('package-lock.json') }} @@ -33,20 +33,26 @@ jobs: - run: npm ci - name: Restore Gradle cache - uses: actions/cache@v2 + uses: actions/cache@26968a09c0ea4f3e233fdddbafd1166051a095f6 # v2.1.4 with: path: ~/.gradle/caches key: ${{ runner.os }}-gradle-${{ hashFiles('**/*.gradle') }} restore-keys: ${{ runner.os }}-gradle - - uses: reactivecircus/android-emulator-runner@v2 + - uses: reactivecircus/android-emulator-runner@08b092e904025fada32a01b711af1e7ff7b7a4a3 # v2.14.3 with: api-level: 28 profile: pixel_xl script: npm run native test:e2e:android:local ${{ matrix.native-test-name }} - - uses: actions/upload-artifact@v2 + - uses: actions/upload-artifact@e448a9b857ee2131e752b06002bf0e093c65e571 # v2.2.2 if: always() with: name: android-screen-recordings path: packages/react-native-editor/android-screen-recordings + + - uses: actions/upload-artifact@e448a9b857ee2131e752b06002bf0e093c65e571 # v2.2.2 + if: always() + with: + name: appium-logs + path: packages/react-native-editor/appium-out.log diff --git a/.github/workflows/rnmobile-ios-runner.yml b/.github/workflows/rnmobile-ios-runner.yml index 3e8e383065839f..60b119ff1ee0c2 100644 --- a/.github/workflows/rnmobile-ios-runner.yml +++ b/.github/workflows/rnmobile-ios-runner.yml @@ -5,7 +5,7 @@ on: paths-ignore: - '**.md' push: - branches: [master] + branches: [trunk] paths-ignore: - '**.md' @@ -14,15 +14,16 @@ jobs: runs-on: macos-latest strategy: matrix: + xcode: [12.2] native-test-name: [ gutenberg-editor-gallery ] steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@5a4ac9002d0be2fb38bd78e4b4dbde5606d7042f # v2.3.4 - name: Restore npm cache - uses: actions/cache@v2 + uses: actions/cache@26968a09c0ea4f3e233fdddbafd1166051a095f6 # v2.1.4 with: path: ~/.npm key: ${{ runner.os }}-npm-${{ hashFiles('package-lock.json') }} @@ -35,13 +36,13 @@ jobs: run: find package-lock.json packages/react-native-editor/ios packages/react-native-aztec/ios packages/react-native-bridge/ios -type f -print0 | sort -z | xargs -0 shasum | tee ios-checksums.txt - name: Restore build cache - uses: actions/cache@v2 + uses: actions/cache@26968a09c0ea4f3e233fdddbafd1166051a095f6 # v2.1.4 with: path: packages/react-native-editor/ios/build/GutenbergDemo/Build/Products/Release-iphonesimulator/GutenbergDemo.app - key: ${{ runner.os }}-ios-build-${{ hashFiles('ios-checksums.txt') }} + key: ${{ runner.os }}-ios-build-${{ matrix.xcode }}-${{ hashFiles('ios-checksums.txt') }} - name: Restore pods cache - uses: actions/cache@v2 + uses: actions/cache@26968a09c0ea4f3e233fdddbafd1166051a095f6 # v2.1.4 with: path: | packages/react-native-editor/ios/Pods @@ -58,11 +59,11 @@ jobs: - name: Bundle iOS run: npm run native test:e2e:bundle:ios - - name: Switch Xcode Version - run: sudo xcode-select --switch /Applications/Xcode_12.app + - name: Switch Xcode version to ${{ matrix.xcode }} + run: sudo xcode-select --switch /Applications/Xcode_${{ matrix.xcode }}.app - name: Build (if needed) - run: test -e packages/react-native-editor/ios/build/GutenbergDemo/Build/Products/Release-iphonesimulator/GutenbergDemo.app/gutenberg || npm run native test:e2e:build-app:ios + run: test -e packages/react-native-editor/ios/build/GutenbergDemo/Build/Products/Release-iphonesimulator/GutenbergDemo.app/GutenbergDemo || npm run native test:e2e:build-app:ios - name: Run iOS Device Tests run: TEST_RN_PLATFORM=ios npm run native device-tests:local ${{ matrix.native-test-name }} @@ -70,8 +71,14 @@ jobs: - name: Prepare build cache run: rm packages/react-native-editor/ios/build/GutenbergDemo/Build/Products/Release-iphonesimulator/GutenbergDemo.app/main.jsbundle - - uses: actions/upload-artifact@v2 + - uses: actions/upload-artifact@e448a9b857ee2131e752b06002bf0e093c65e571 # v2.2.2 if: always() with: name: ios-screen-recordings path: packages/react-native-editor/ios-screen-recordings + + - uses: actions/upload-artifact@e448a9b857ee2131e752b06002bf0e093c65e571 # v2.2.2 + if: always() + with: + name: appium-logs + path: packages/react-native-editor/appium-out.log diff --git a/.github/workflows/stale-issue-add-needs-testing.yml b/.github/workflows/stale-issue-add-needs-testing.yml new file mode 100644 index 00000000000000..a963f97287939e --- /dev/null +++ b/.github/workflows/stale-issue-add-needs-testing.yml @@ -0,0 +1,17 @@ +name: "Mark old issues as needs confirmation" +on: + schedule: + - cron: "45 1 * * *" + +jobs: + stale: + runs-on: ubuntu-latest + steps: + - uses: actions/stale@996798eb71ef485dc4c7b4d3285842d714040c4a # v3.0.17 + with: + repo-token: ${{ secrets.GITHUB_TOKEN }} + stale-issue-message: "Hi,\nThis issue has gone 180 days without any activity. This means it is time for a check-in to make sure it is still relevant. If you are still experiencing this issue with the latest versions, you can help the project by responding to confirm the problem and by providing any updated reproduction steps.\nThanks for helping out." + days-before-stale: 180 + days-before-close: -1 + remove-stale-when-updated: false + stale-issue-label: 'Needs Testing' diff --git a/.github/workflows/stale-issue-mark-stale.yml b/.github/workflows/stale-issue-mark-stale.yml new file mode 100644 index 00000000000000..91d29cccedbe8f --- /dev/null +++ b/.github/workflows/stale-issue-mark-stale.yml @@ -0,0 +1,17 @@ +name: "Mark issues stale after needs testing for 30 days" +on: + schedule: + - cron: "55 1 * * *" + +jobs: + stale: + runs-on: ubuntu-latest + steps: + - uses: actions/stale@996798eb71ef485dc4c7b4d3285842d714040c4a # v3.0.17 + with: + repo-token: ${{ secrets.GITHUB_TOKEN }} + days-before-stale: 30 + days-before-close: -1 + only-labels: 'Needs Testing' + skip-stale-issue-message: true + stale-issue-label: '[Status] Stale' diff --git a/.github/workflows/stale-issue-needs-info.yml b/.github/workflows/stale-issue-needs-info.yml new file mode 100644 index 00000000000000..7dede45c224ed4 --- /dev/null +++ b/.github/workflows/stale-issue-needs-info.yml @@ -0,0 +1,17 @@ +name: "Mark issues stale that require info" +on: + schedule: + - cron: "30 1 * * *" + +jobs: + stale: + runs-on: ubuntu-latest + steps: + - uses: actions/stale@996798eb71ef485dc4c7b4d3285842d714040c4a # v3.0.17 + with: + repo-token: ${{ secrets.GITHUB_TOKEN }} + stale-issue-message: 'Help us move this issue forward. This issue is being marked stale since it has no activity after 15 days of requesting more information. Please add info requested so we can help move the issue forward. Note: The triage policy is to close stale issues that need more info and no response after 2 weeks.' + days-before-stale: 15 + days-before-close: -1 + only-labels: '[Status] Needs More Info' + stale-issue-label: '[Status] Stale' diff --git a/.github/workflows/static-checks.yml b/.github/workflows/static-checks.yml index 9ca88f6d094c91..ad10daa5a167fb 100644 --- a/.github/workflows/static-checks.yml +++ b/.github/workflows/static-checks.yml @@ -3,7 +3,9 @@ name: Static Analysis (Linting, License, Type checks...) on: pull_request: push: - branches: [master] + branches: + - trunk + - 'wp/**' jobs: check: @@ -12,10 +14,10 @@ jobs: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@5a4ac9002d0be2fb38bd78e4b4dbde5606d7042f # v2.3.4 - name: Cache node modules - uses: actions/cache@v2 + uses: actions/cache@26968a09c0ea4f3e233fdddbafd1166051a095f6 # v2.1.4 env: cache-name: cache-node-modules with: @@ -28,7 +30,7 @@ jobs: ${{ runner.os }}- - name: Use Node.js 14.x - uses: actions/setup-node@v1 + uses: actions/setup-node@46071b5c7a2e0c34e49c3cb8a0e792e86e18d5ea # v2.1.5 with: node-version: 14.x diff --git a/.github/workflows/storybook-pages.yml b/.github/workflows/storybook-pages.yml index f3a956c75841d6..5ea64c67899344 100644 --- a/.github/workflows/storybook-pages.yml +++ b/.github/workflows/storybook-pages.yml @@ -3,19 +3,19 @@ name: Storybook GitHub Pages on: push: branches: - - master + - trunk jobs: deploy: runs-on: ubuntu-latest steps: - name: Checkout - uses: actions/checkout@v2 + uses: actions/checkout@5a4ac9002d0be2fb38bd78e4b4dbde5606d7042f # v2.3.4 with: - ref: master + ref: trunk - name: Cache node modules - uses: actions/cache@v2 + uses: actions/cache@26968a09c0ea4f3e233fdddbafd1166051a095f6 # v2.1.4 env: cache-name: cache-node-modules with: @@ -28,7 +28,7 @@ jobs: ${{ runner.os }}- - name: Setup Node - uses: actions/setup-node@v1 + uses: actions/setup-node@46071b5c7a2e0c34e49c3cb8a0e792e86e18d5ea # v2.1.5 with: node-version: '14.x' @@ -39,7 +39,7 @@ jobs: run: npm run storybook:build - name: Deploy - uses: peaceiris/actions-gh-pages@v3 + uses: peaceiris/actions-gh-pages@bbdfb200618d235585ad98e965f4aafc39b4c501 # v3.7.3 with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: ./storybook/build diff --git a/.github/workflows/unit-test.yml b/.github/workflows/unit-test.yml index 35aa4c4a1a34b8..a5ccf320fbef50 100644 --- a/.github/workflows/unit-test.yml +++ b/.github/workflows/unit-test.yml @@ -1,25 +1,28 @@ name: Unit Tests +# Since Unit Tests are required to pass for each PR, +# we cannot disable them for documentation-only changes. on: pull_request: - paths-ignore: - - '**.md' push: - branches: [master] - paths-ignore: - - '**.md' + branches: + - trunk + - 'wp/**' jobs: unit-js: name: JavaScript - runs-on: ubuntu-latest + strategy: + fail-fast: false + matrix: + node: [12, 14] steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@5a4ac9002d0be2fb38bd78e4b4dbde5606d7042f # v2.3.4 - name: Cache node modules - uses: actions/cache@v2 + uses: actions/cache@26968a09c0ea4f3e233fdddbafd1166051a095f6 # v2.1.4 env: cache-name: cache-node-modules with: @@ -31,10 +34,10 @@ jobs: ${{ runner.os }}-build- ${{ runner.os }}- - - name: Use Node.js 14.x - uses: actions/setup-node@v1 + - name: Use Node.js ${{ matrix.node }}.x + uses: actions/setup-node@46071b5c7a2e0c34e49c3cb8a0e792e86e18d5ea # v2.1.5 with: - node-version: 14.x + node-version: ${{ matrix.node }} - name: Npm install and build # It's not necessary to run the full build, since Jest can interpret @@ -56,10 +59,10 @@ jobs: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@5a4ac9002d0be2fb38bd78e4b4dbde5606d7042f # v2.3.4 - name: Cache node modules - uses: actions/cache@v2 + uses: actions/cache@26968a09c0ea4f3e233fdddbafd1166051a095f6 # v2.1.4 env: cache-name: cache-node-modules with: @@ -72,7 +75,7 @@ jobs: ${{ runner.os }}- - name: Use Node.js 14.x - uses: actions/setup-node@v1 + uses: actions/setup-node@46071b5c7a2e0c34e49c3cb8a0e792e86e18d5ea # v2.1.5 with: node-version: 14.x @@ -92,7 +95,7 @@ jobs: - name: Running single site unit tests run: npm run test-unit-php if: ${{ success() || failure() }} - + - name: Running multisite unit tests run: npm run test-unit-php-multisite if: ${{ success() || failure() }} @@ -104,10 +107,10 @@ jobs: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@5a4ac9002d0be2fb38bd78e4b4dbde5606d7042f # v2.3.4 - name: Cache node modules - uses: actions/cache@v2 + uses: actions/cache@26968a09c0ea4f3e233fdddbafd1166051a095f6 # v2.1.4 env: cache-name: cache-node-modules with: @@ -120,7 +123,7 @@ jobs: ${{ runner.os }}- - name: Use Node.js 14.x - uses: actions/setup-node@v1 + uses: actions/setup-node@46071b5c7a2e0c34e49c3cb8a0e792e86e18d5ea # v2.1.5 with: node-version: 14.x diff --git a/.github/workflows/upload-release-to-plugin-repo.yml b/.github/workflows/upload-release-to-plugin-repo.yml new file mode 100644 index 00000000000000..57df6897e9553c --- /dev/null +++ b/.github/workflows/upload-release-to-plugin-repo.yml @@ -0,0 +1,64 @@ +on: + release: + types: [released] + +name: Upload Gutenberg plugin to WordPress.org plugin repo + +jobs: + upload: + name: Upload Gutenberg Plugin + runs-on: ubuntu-latest + environment: wp.org plugin + if: github.event.release.assets[0] + env: + PLUGIN_REPO_URL: 'https://plugins.svn.wordpress.org/gutenberg' + STABLE_TAG_REGEX: 'Stable tag: [0-9]\+\.[0-9]\+\.[0-9]\+\s*' + SVN_USERNAME: ${{ secrets.svn_username }} + SVN_PASSWORD: ${{ secrets.svn_password }} + VERSION: ${{ github.event.release.name }} + steps: + - name: Check out Gutenberg trunk from WP.org plugin repo + run: svn checkout "$PLUGIN_REPO_URL/trunk" + + - name: Get previous stable tag + id: get_previous_stable_tag + run: echo ::set-output name=stable_tag::$(grep "$STABLE_TAG_REGEX" ./trunk/readme.txt) + + - name: Delete everything + working-directory: ./trunk + run: find . -maxdepth 1 -not -name ".svn" -not -name "." -not -name ".." -exec rm -rf {} + + + - name: Download and unzip Gutenberg plugin asset into trunk folder + env: + PLUGIN_URL: ${{ github.event.release.assets[0].browser_download_url }} + run: | + curl -L -o gutenberg.zip $PLUGIN_URL + unzip gutenberg.zip -d trunk + rm gutenberg.zip + + - name: Replace the stable tag placeholder with the existing stable tag on the SVN repository + env: + STABLE_TAG_PLACEHOLDER: 'Stable tag: V\.V\.V' + STABLE_TAG: ${{ steps.get_previous_stable_tag.outputs.stable_tag }} + run: sed -i "s/${STABLE_TAG_PLACEHOLDER}/${STABLE_TAG}/g" ./trunk/readme.txt + + - name: Commit the content changes + working-directory: ./trunk + run: | + svn st | grep '^?' | awk '{print $2}' | xargs -r svn add + svn st | grep '^!' | awk '{print $2}' | xargs -r svn rm + svn commit -m "Committing version $VERSION" \ + --no-auth-cache --non-interactive --username "$SVN_USERNAME" --password "$SVN_PASSWORD" + + - name: Create the SVN tag + working-directory: ./trunk + run: | + svn copy "$PLUGIN_REPO_URL/trunk" "$PLUGIN_REPO_URL/tags/$VERSION" -m "Tagging version $VERSION" \ + --no-auth-cache --non-interactive --username "$SVN_USERNAME" --password "$SVN_PASSWORD" + + - name: Update the plugin's stable version + working-directory: ./trunk + run: | + sed -i "s/${STABLE_TAG_REGEX}/Stable tag: ${VERSION}/g" ./readme.txt + svn commit -m "Releasing version $VERSION" \ + --no-auth-cache --non-interactive --username "$SVN_USERNAME" --password "$SVN_PASSWORD" diff --git a/.gitignore b/.gitignore index d79599e194f3cf..b0a128b5a01734 100644 --- a/.gitignore +++ b/.gitignore @@ -11,7 +11,6 @@ gutenberg.zip *.log phpcs.xml yarn.lock -/wordpress /artifacts .cache diff --git a/.stylelintrc.json b/.stylelintrc.json index cca0df1542f3d0..3d4ff66523fe3b 100644 --- a/.stylelintrc.json +++ b/.stylelintrc.json @@ -1,5 +1,5 @@ { - "extends": "stylelint-config-wordpress", + "extends": "@wordpress/stylelint-config", "rules": { "at-rule-empty-line-before": null, "at-rule-no-unknown": null, diff --git a/.wp-env.json b/.wp-env.json index ccd1231aa28b25..4d67d71c82fb55 100644 --- a/.wp-env.json +++ b/.wp-env.json @@ -3,7 +3,7 @@ "plugins": [ "." ], - "themes": [ "WordPress/theme-experiments/tt1-blocks" ], + "themes": [ "WordPress/theme-experiments/tt1-blocks#tt1-blocks@0.4.3" ], "env": { "tests": { "mappings": { diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9381a3cd9f2af5..942cc50b1d0a3a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,13 +4,13 @@ Welcome to WordPress' Gutenberg project! We hope you join us in creating the fut ## How can I contribute? -To learn all about contributing to the Gutenberg project, see the [Contributor Guide](/docs/contributors/readme.md). The handbook includes all the details you need to get setup and start shaping the future of web publishing. +To learn all about contributing to the Gutenberg project, see the [Contributor Guide](/docs/contributors/README.md). The handbook includes all the details you need to get setup and start shaping the future of web publishing. -- Code? See the [developer section](/docs/contributors/develop.md). +- Code? See the [developer section](/docs/contributors/code/README.md). -- Design? See the [design section](/docs/contributors/design.md). +- Design? See the [design section](/docs/contributors/design/README.md). -- Documentation? See the [documentation section](/docs/contributors/document.md). +- Documentation? See the [documentation section](/docs/contributors/documentation/README.md). - Triage? We need help reviewing existing issues to make sure they’re relevant and actionable. Triage is an important contribution because it allows us to work on the highest priority issues. To learn more, please see the [triaging issues section](docs/contributors/triage.md). diff --git a/LICENSE.md b/LICENSE.md index c603e7f5dd0bd0..a6523290d51581 100644 --- a/LICENSE.md +++ b/LICENSE.md @@ -1,6 +1,6 @@ ### WordPress - Web publishing software - Copyright 2011-2020 by the contributors + Copyright 2011-2021 by the contributors This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by @@ -34,14 +34,14 @@ and Copyright 2003-2010 by the contributors WordPress is released under the GPL - + --- ### GNU GENERAL PUBLIC LICENSE Version 2, June 1991 - Copyright (C) 1989, 1991 Free Software Foundation, Inc. + Copyright (C) 1989, 1991 Free Software Foundation, Inc. 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA Everyone is permitted to copy and distribute verbatim copies @@ -135,17 +135,17 @@ portion of it, thus forming a work based on the Program, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions: - + **a)** You must cause the modified files to carry prominent notices stating that you changed the files and the date of any change. - + **b)** You must cause any work that you distribute or publish, that in whole or in part contains or is derived from the Program or any part thereof, to be licensed as a whole at no charge to all third parties under the terms of this License. - + **c)** If the modified program normally reads commands interactively when run, you must cause it, when started running for such interactive use in the most ordinary way, to print or display an announcement @@ -182,12 +182,12 @@ the scope of this License. under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you also do one of the following: - + **a)** Accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or, - + **b)** Accompany it with a written offer, valid for at least three years, to give any third party, for a charge no more than your cost of physically performing source distribution, a complete machine-readable @@ -195,7 +195,7 @@ copy of the corresponding source code, to be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or, - + **c)** Accompany it with the information you received as to the offer to distribute corresponding source code. (This alternative is allowed only for noncommercial distribution and only if you received the @@ -370,7 +370,7 @@ when it starts in an interactive mode: Gnomovision version 69, Copyright (C) year name of author Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. This is free software, and you are welcome - to redistribute it under certain conditions; type `show c' + to redistribute it under certain conditions; type `show c' for details. The hypothetical commands \`show w' and \`show c' should show the @@ -385,7 +385,7 @@ if necessary. Here is a sample; alter the names: Yoyodyne, Inc., hereby disclaims all copyright interest in the program `Gnomovision' - (which makes passes at compilers) written + (which makes passes at compilers) written by James Hacker. signature of Ty Coon, 1 April 1989 diff --git a/README.md b/README.md index b5570c6dafdd13..dd556dbd03eb23 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,11 @@ # Gutenberg -[![End-to-End Tests](https://github.com/WordPress/gutenberg/workflows/End-to-End%20Tests/badge.svg)](https://github.com/WordPress/gutenberg/actions?query=workflow%3A%22End-to-End+Tests%22+branch%3Amaster) -[![Static Analysis (Linting, License, Type checks...)](https://github.com/WordPress/gutenberg/workflows/Static%20Analysis%20(Linting,%20License,%20Type%20checks...)/badge.svg)](https://github.com/WordPress/gutenberg/actions?query=workflow%3A%22Static+Analysis+%28Linting%2C+License%2C+Type+checks...%29%22+branch%3Amaster) -[![Unit Tests](https://github.com/WordPress/gutenberg/workflows/Unit%20Tests/badge.svg)](https://github.com/WordPress/gutenberg/actions?query=workflow%3A%22Unit+Tests%22+branch%3Amaster) -[![Create Block](https://github.com/WordPress/gutenberg/workflows/Create%20Block/badge.svg)](https://github.com/WordPress/gutenberg/actions?query=workflow%3A%22Create+Block%22+branch%3Amaster) -[![React Native E2E Tests (iOS)](https://github.com/WordPress/gutenberg/workflows/React%20Native%20E2E%20Tests%20(iOS)/badge.svg)](https://github.com/WordPress/gutenberg/actions?query=workflow%3A%22React+Native+E2E+Tests+%28iOS%29%22+branch%3Amaster) -[![React Native E2E Tests (Android)](https://github.com/WordPress/gutenberg/workflows/React%20Native%20E2E%20Tests%20(Android)/badge.svg)](https://github.com/WordPress/gutenberg/actions?query=workflow%3A%22React+Native+E2E+Tests+%28Android%29%22+branch%3Amaster) +[![End-to-End Tests](https://github.com/WordPress/gutenberg/workflows/End-to-End%20Tests/badge.svg)](https://github.com/WordPress/gutenberg/actions?query=workflow%3A%22End-to-End+Tests%22+branch%3Atrunk) +[![Static Analysis (Linting, License, Type checks...)](https://github.com/WordPress/gutenberg/workflows/Static%20Analysis%20(Linting,%20License,%20Type%20checks...)/badge.svg)](https://github.com/WordPress/gutenberg/actions?query=workflow%3A%22Static+Analysis+%28Linting%2C+License%2C+Type+checks...%29%22+branch%3Atrunk) +[![Unit Tests](https://github.com/WordPress/gutenberg/workflows/Unit%20Tests/badge.svg)](https://github.com/WordPress/gutenberg/actions?query=workflow%3A%22Unit+Tests%22+branch%3Atrunk) +[![Create Block](https://github.com/WordPress/gutenberg/workflows/Create%20Block/badge.svg)](https://github.com/WordPress/gutenberg/actions?query=workflow%3A%22Create+Block%22+branch%3Atrunk) +[![React Native E2E Tests (iOS)](https://github.com/WordPress/gutenberg/workflows/React%20Native%20E2E%20Tests%20(iOS)/badge.svg)](https://github.com/WordPress/gutenberg/actions?query=workflow%3A%22React+Native+E2E+Tests+%28iOS%29%22+branch%3Atrunk) +[![React Native E2E Tests (Android)](https://github.com/WordPress/gutenberg/workflows/React%20Native%20E2E%20Tests%20(Android)/badge.svg)](https://github.com/WordPress/gutenberg/actions?query=workflow%3A%22React+Native+E2E+Tests+%28Android%29%22+branch%3Atrunk) [![lerna](https://img.shields.io/badge/maintained%20with-lerna-cc00ff.svg)](https://lerna.js.org) @@ -13,9 +13,9 @@ Welcome to the development hub for the WordPress Gutenberg project! -"Gutenberg" is a codename for a whole new paradigm in WordPress site building and publishing, that aims to revolutionize the entire publishing experience as much as Gutenberg did the printed word. Right now, the project is in the first phase of a four-phase process that will touch every piece of WordPress -- Editing, Customization, Collaboration, and Multilingual -- and is focused on a new editing experience, the block editor. +"Gutenberg" is a codename for a whole new paradigm in WordPress site building and publishing, that aims to revolutionize the entire publishing experience as much as Gutenberg did the printed word. Right now, the project is in the second phase of a four-phase process that will touch every piece of WordPress -- Editing, **Customization** (which includes Full Site Editing, Block Patterns, Block Directory and Block based themes), Collaboration, and Multilingual -- and is focused on a new editing experience, the block editor. -The block editor introduces a modular approach to pages and posts: each piece of content in the editor, from a paragraph to an image gallery to a headline, is its own block. And just like physical blocks, WordPress blocks can added, arranged, and rearranged, allowing WordPress users to create media-rich pages in a visually intuitive way -- and without work-arounds like shortcodes or custom HTML. +The block editor introduces a modular approach to pages and posts: each piece of content in the editor, from a paragraph to an image gallery to a headline, is its own block. And just like physical blocks, WordPress blocks can be added, arranged, and rearranged, allowing WordPress users to create media-rich pages in a visually intuitive way -- and without work-arounds like shortcodes or custom HTML. The block editor first became available in December 2018, and we're still hard at work refining the experience, creating more and better blocks, and laying the groundwork for the next three phases of work. The Gutenberg plugin gives you the latest version of the block editor so you can join us in testing bleeding-edge features, start playing with blocks, and maybe get inspired to build your own. @@ -35,15 +35,15 @@ Get hands on: check out the [block editor live demo](https://wordpress.org/guten Extending and customizing is at the heart of the WordPress platform, this is no different for the Gutenberg project. The editor and future products can be extended by third-party developers using plugins. -Review the [Create a Block tutorial](/docs/designers-developers/developers/tutorials/create-block/readme.md) for the fastest way to get started extending the block editor. See the [Developer Documentation](https://developer.wordpress.org/block-editor/developers/) for extensive tutorials, documentation, and API references. +Review the [Create a Block tutorial](/docs/getting-started/tutorials/create-block/README.md) for the fastest way to get started extending the block editor. See the [Developer Documentation](https://developer.wordpress.org/block-editor/#develop-for-the-block-editor) for extensive tutorials, documentation, and API references. ### Contribute to Gutenberg Gutenberg is an open-source project and welcomes all contributors from code to design, from documentation to triage. The project is built by many contributors and volunteers and we'd love your help building it. -See the [Contributors Handbook](https://developer.wordpress.org/block-editor/contributors/) for all the details on how you can contribute. See [CONTRIBUTING.md](https://github.com/WordPress/gutenberg/blob/master/CONTRIBUTING.md) for the contributing guidelines. +See the [Contributors Handbook](https://developer.wordpress.org/block-editor/contributors/) for all the details on how you can contribute. See [CONTRIBUTING.md](https://github.com/WordPress/gutenberg/blob/HEAD/CONTRIBUTING.md) for the contributing guidelines. -As with all WordPress projects, we want to ensure a welcoming environment for everyone. With that in mind, all contributors are expected to follow our [Code of Conduct](https://github.com/WordPress/gutenberg/blob/master/CODE_OF_CONDUCT.md). +As with all WordPress projects, we want to ensure a welcoming environment for everyone. With that in mind, all contributors are expected to follow our [Code of Conduct](https://github.com/WordPress/gutenberg/blob/HEAD/CODE_OF_CONDUCT.md). ## Get Involved diff --git a/bin/api-docs/update-api-docs.js b/bin/api-docs/update-api-docs.js index c1643d2f632f93..3ee55ff0c3d814 100755 --- a/bin/api-docs/update-api-docs.js +++ b/bin/api-docs/update-api-docs.js @@ -43,13 +43,6 @@ const DATA_DOCS_DIR = resolve( 'docs/designers-developers/developers/data' ); -/** - * Default path to use if the token doesn't include one. - * - * @see TOKEN_PATTERN - */ -const DEFAULT_PATH = 'src/index.js'; - /** * Pattern matching start token of a README file. * @@ -64,7 +57,6 @@ const DEFAULT_PATH = 'src/index.js'; * * * @type {RegExp} - * @see DEFAULT_PATH */ const TOKEN_PATTERN = //g; @@ -169,7 +161,7 @@ const filterTokenTransform = new Transform( { const tokens = []; for ( const match of content.matchAll( TOKEN_PATTERN ) ) { - const [ , token, path = DEFAULT_PATH ] = match; + const [ , token, path ] = match; tokens.push( [ token, path ] ); } @@ -182,6 +174,23 @@ const filterTokenTransform = new Transform( { }, } ); +/** + * Find default source file (`src/index.{js,ts,tsx}`) in a specified package directory + * + * @param {string} dir Package directory to search in + * @return {string} Name of matching file + */ +function findDefaultSourcePath( dir ) { + const defaultPathMatches = glob.sync( 'src/index.{js,ts,tsx}', { + cwd: dir, + } ); + if ( ! defaultPathMatches.length ) { + throw new Error( `Cannot find default source file in ${ dir }` ); + } + // @ts-ignore + return defaultPathMatches[ 0 ]; +} + /** * Optional process arguments for which to generate documentation. * @@ -202,8 +211,11 @@ glob.stream( [ // represented by tokens. The docgen script updates one token at a time, // so the tokens must be replaced in sequence to prevent the processes // from overriding each other. - for ( const [ token, path ] of tokens ) { - try { + try { + for ( const [ + token, + path = findDefaultSourcePath( dirname( file ) ), + ] of tokens ) { await execa( `"${ join( __dirname, @@ -222,9 +234,9 @@ glob.stream( [ ], { shell: true } ); - } catch ( error ) { - console.error( error ); - process.exit( 1 ); } + } catch ( error ) { + console.error( error ); + process.exit( 1 ); } } ); diff --git a/bin/build-plugin-zip.sh b/bin/build-plugin-zip.sh index a8e91093205a2f..5d9de9b55b79ef 100755 --- a/bin/build-plugin-zip.sh +++ b/bin/build-plugin-zip.sh @@ -111,8 +111,11 @@ mv gutenberg.tmp.php gutenberg.php build_files=$( ls build/*/*.{js,css,asset.php} \ - build/block-library/blocks/*.php build/block-library/blocks/*/block.json \ - build/edit-widgets/blocks/*.php build/edit-widgets/blocks/*/block.json \ + build/block-library/blocks/*.php \ + build/block-library/blocks/*/block.json \ + build/block-library/blocks/*/*.css \ + build/edit-widgets/blocks/*.php \ + build/edit-widgets/blocks/*/block.json \ ) diff --git a/bin/check-latest-npm.js b/bin/check-latest-npm.js index 95be20a0553f27..f4da80754af321 100644 --- a/bin/check-latest-npm.js +++ b/bin/check-latest-npm.js @@ -6,12 +6,22 @@ const { green, red, yellow } = require( 'chalk' ); const { get } = require( 'https' ); const { spawn } = require( 'child_process' ); +const semver = require( 'semver' ); + +/** + * Internal dependencies + */ +const { + engines: { npm: npmRange }, + // Ignore reason: `package.json` exists outside `bin` `rootDir`. + // @ts-ignore +} = require( '../package.json' ); /** * Returns a promise resolving with the version number of the latest available - * version of NPM. + * version of npm. * - * @return {Promise} Promise resolving with latest NPM version. + * @return {Promise} Promise resolving with latest npm version. */ async function getLatestNPMVersion() { return new Promise( ( resolve, reject ) => { @@ -23,14 +33,14 @@ async function getLatestNPMVersion() { // will return an abbreviated form of the package data which // includes enough detail to determine the latest version. // - // See: https://github.com/npm/registry/blob/master/docs/responses/package-metadata.md + // See: https://github.com/npm/registry/blob/HEAD/docs/responses/package-metadata.md Accept: 'application/vnd.npm.install-v1+json', }, }, async ( response ) => { if ( response.statusCode !== 200 ) { return reject( - new Error( 'Package data for NPM not found' ) + new Error( 'Package data for npm not found' ) ); } @@ -45,23 +55,25 @@ async function getLatestNPMVersion() { } catch { return reject( new Error( - 'Package data for NPM returned invalid response body' + 'Package data for npm returned invalid response body' ) ); } - resolve( data[ 'dist-tags' ].latest ); + const versions = Object.values( data[ 'dist-tags' ] ); + + resolve( semver.maxSatisfying( versions, npmRange ) ); } ).on( 'error', ( error ) => { if ( /** @type {NodeJS.ErrnoException} */ ( error ).code === 'ENOTFOUND' ) { - error = new Error( `Could not contact the NPM registry to determine latest version. + error = new Error( `Could not contact the npm registry to determine latest version. This could be due to an intermittent outage of the service, or because you are not connected to the internet. -Because it is important that \`package-lock.json\` files only be committed while running the latest version of NPM, this commit has been blocked. +Because it is important that \`package-lock.json\` files only be committed while running the latest version of npm, this commit has been blocked. If you are certain of your changes and desire to commit anyways, you should either connect to the internet or bypass commit verification using ${ yellow( 'git commit --no-verify' @@ -75,9 +87,9 @@ If you are certain of your changes and desire to commit anyways, you should eith /** * Returns a promise resolving with the version number of the local installed - * version of NPM. + * version of npm. * - * @return {Promise} Promise resolving with local installed NPM version. + * @return {Promise} Promise resolving with local installed npm version. */ async function getLocalNPMVersion() { return new Promise( async ( resolve ) => { @@ -99,15 +111,15 @@ Promise.all( [ getLatestNPMVersion(), getLocalNPMVersion() ] ) .then( ( [ latest, local ] ) => { if ( latest !== local ) { throw new Error( - `The local NPM version does not match the expected latest version. Expected ${ green( + `The local npm version does not match the expected latest version. Expected ${ green( latest ) }, found ${ red( local ) }. -It is required that you have the latest version of NPM installed in order to commit a change to the package-lock.json file. +It is required that you have the expected latest version of npm installed in order to commit a change to the package-lock.json file. Run ${ yellow( - 'npm install --global npm@latest' - ) } to install the latest version of NPM. Before retrying your commit, run ${ yellow( + `npm install --global npm@${ latest }` + ) } to install the expected latest version of npm. Before retrying your commit, run ${ yellow( 'npm install' ) } once more to ensure the package-lock.json contents are correct. If there are any changes to the file, they should be included in your commit.` ); @@ -115,7 +127,7 @@ Run ${ yellow( } ) .catch( ( error ) => { console.error( - 'Latest NPM check failed!\n\n' + error.toString() + '\n' + 'Latest npm check failed!\n\n' + error.toString() + '\n' ); process.exitCode = 1; } ); diff --git a/bin/packages/build-worker.js b/bin/packages/build-worker.js index 31e5c3bb17ed8b..b9c7e96f21d7bb 100644 --- a/bin/packages/build-worker.js +++ b/bin/packages/build-worker.js @@ -76,99 +76,106 @@ function getBuildPath( file, buildFolder ) { return path.resolve( pkgBuildPath, relativeToSrcPath ); } -/** - * Object of build tasks per file extension. - * - * @type {Object} - */ -const BUILD_TASK_BY_EXTENSION = { - async '.scss'( file ) { - const outputFile = getBuildPath( - file.replace( '.scss', '.css' ), - 'build-style' +async function buildCSS( file ) { + const outputFile = getBuildPath( + file.replace( '.scss', '.css' ), + 'build-style' + ); + const outputFileRTL = getBuildPath( + file.replace( '.scss', '-rtl.css' ), + 'build-style' + ); + + const [ , contents ] = await Promise.all( [ + makeDir( path.dirname( outputFile ) ), + readFile( file, 'utf8' ), + ] ); + const builtSass = await renderSass( { + file, + includePaths: [ path.join( PACKAGES_DIR, 'base-styles' ) ], + data: + [ + 'colors', + 'breakpoints', + 'variables', + 'mixins', + 'animations', + 'z-index', + ] + // Editor styles should be excluded from the default CSS vars output. + .concat( + file.includes( 'common.scss' ) || + ( ! file.includes( 'block-library' ) && + ! file.includes( 'editor-styles.scss' ) ) + ? [ 'default-custom-properties' ] + : [] + ) + .map( ( imported ) => `@import "${ imported }";` ) + .join( ' ' ) + contents, + } ); + + const result = await postcss( + require( '@wordpress/postcss-plugins-preset' ) + ).process( builtSass.css, { + from: 'src/app.css', + to: 'dest/app.css', + } ); + + const resultRTL = await postcss( [ require( 'rtlcss' )() ] ).process( + result.css, + { + from: 'src/app.css', + to: 'dest/app.css', + } + ); + + await Promise.all( [ + writeFile( outputFile, result.css ), + writeFile( outputFileRTL, resultRTL.css ), + ] ); +} + +async function buildJS( file ) { + for ( const [ environment, buildDir ] of Object.entries( + JS_ENVIRONMENTS + ) ) { + const destPath = getBuildPath( + file.replace( /\.tsx?$/, '.js' ), + buildDir ); - const outputFileRTL = getBuildPath( - file.replace( '.scss', '-rtl.css' ), - 'build-style' + const babelOptions = getBabelConfig( + environment, + file.replace( PACKAGES_DIR, '@wordpress' ) ); - const [ , contents ] = await Promise.all( [ - makeDir( path.dirname( outputFile ) ), - readFile( file, 'utf8' ), + const [ , transformed ] = await Promise.all( [ + makeDir( path.dirname( destPath ) ), + babel.transformFileAsync( file, babelOptions ), ] ); - const builtSass = await renderSass( { - file, - includePaths: [ path.join( PACKAGES_DIR, 'base-styles' ) ], - data: - [ - 'colors', - 'breakpoints', - 'variables', - 'mixins', - 'animations', - 'z-index', - ] - // Editor styles should be excluded from the default CSS vars output. - .concat( - file.includes( 'editor-styles.scss' ) - ? [] - : [ 'default-custom-properties' ] - ) - .map( ( imported ) => `@import "${ imported }";` ) - .join( ' ' ) + contents, - } ); - - const result = await postcss( - require( '@wordpress/postcss-plugins-preset' ) - ).process( builtSass.css, { - from: 'src/app.css', - to: 'dest/app.css', - } ); - - const resultRTL = await postcss( [ require( 'rtlcss' )() ] ).process( - result.css, - { - from: 'src/app.css', - to: 'dest/app.css', - } - ); await Promise.all( [ - writeFile( outputFile, result.css ), - writeFile( outputFileRTL, resultRTL.css ), + writeFile( destPath + '.map', JSON.stringify( transformed.map ) ), + writeFile( + destPath, + transformed.code + + '\n//# sourceMappingURL=' + + path.basename( destPath ) + + '.map' + ), ] ); - }, - - async '.js'( file ) { - for ( const [ environment, buildDir ] of Object.entries( - JS_ENVIRONMENTS - ) ) { - const destPath = getBuildPath( file, buildDir ); - const babelOptions = getBabelConfig( - environment, - file.replace( PACKAGES_DIR, '@wordpress' ) - ); - - const [ , transformed ] = await Promise.all( [ - makeDir( path.dirname( destPath ) ), - babel.transformFileAsync( file, babelOptions ), - ] ); - - await Promise.all( [ - writeFile( - destPath + '.map', - JSON.stringify( transformed.map ) - ), - writeFile( - destPath, - transformed.code + - '\n//# sourceMappingURL=' + - path.basename( destPath ) + - '.map' - ), - ] ); - } - }, + } +} + +/** + * Object of build tasks per file extension. + * + * @type {Object} + */ +const BUILD_TASK_BY_EXTENSION = { + '.scss': buildCSS, + '.js': buildJS, + '.ts': buildJS, + '.tsx': buildJS, }; module.exports = async ( file, callback ) => { @@ -176,7 +183,7 @@ module.exports = async ( file, callback ) => { const task = BUILD_TASK_BY_EXTENSION[ extension ]; if ( ! task ) { - return; + callback( new Error( `No handler for extension: ${ extension }` ) ); } try { diff --git a/bin/packages/build.js b/bin/packages/build.js index f2a9e381875f2e..397a136ba72468 100755 --- a/bin/packages/build.js +++ b/bin/packages/build.js @@ -194,7 +194,7 @@ if ( files.length ) { stream = glob.stream( [ - `${ PACKAGES_DIR }/*/src/**/*.js`, + `${ PACKAGES_DIR }/*/src/**/*.{js,ts,tsx}`, `${ PACKAGES_DIR }/*/src/*.scss`, `${ PACKAGES_DIR }/block-library/src/**/*.js`, `${ PACKAGES_DIR }/block-library/src/*/style.scss`, diff --git a/bin/plugin/cli.js b/bin/plugin/cli.js index 84db72639f6b2a..c1a978c33b131d 100755 --- a/bin/plugin/cli.js +++ b/bin/plugin/cli.js @@ -21,8 +21,8 @@ const catchException = ( command ) => { */ const { releaseRC, releaseStable } = require( './commands/release' ); const { - prepareLatestDistTag, - prepareNextDistTag, + publishNpmLatestDistTag, + publishNpmNextDistTag, } = require( './commands/packages' ); const { getReleaseChangelog } = require( './commands/changelog' ); const { runPerformanceTests } = require( './commands/performance' ); @@ -40,26 +40,30 @@ program .action( catchException( releaseStable ) ); program - .command( 'prepare-packages-stable' ) - .alias( 'npm-stable' ) + .command( 'publish-npm-packages-latest' ) + .alias( 'npm-latest' ) .description( - 'Prepares the packages to be published to npm as stable (latest dist-tag, production version)' + 'Publishes packages to npm (latest dist-tag, production version)' ) - .action( catchException( prepareLatestDistTag ) ); + .action( catchException( publishNpmLatestDistTag ) ); program - .command( 'prepare-packages-rc' ) - .alias( 'npm-rc' ) + .command( 'publish-npm-packages-next' ) + .alias( 'npm-next' ) .description( - 'Prepares the packages to be published to npm as RC (next dist-tag, RC version)' + 'Publishes packages to npm (next dist-tag, prerelease version)' ) - .action( catchException( prepareNextDistTag ) ); + .action( catchException( publishNpmNextDistTag ) ); program .command( 'release-plugin-changelog' ) .alias( 'changelog' ) .option( '-m, --milestone ', 'Milestone' ) .option( '-t, --token ', 'Github token' ) + .option( + '-u, --unreleased', + "Only include PRs that haven't been included in a release yet" + ) .description( 'Generates a changelog from merged Pull Requests' ) .action( catchException( getReleaseChangelog ) ); diff --git a/bin/plugin/commands/changelog.js b/bin/plugin/commands/changelog.js index 85fb494422234b..0c2af1242a1562 100644 --- a/bin/plugin/commands/changelog.js +++ b/bin/plugin/commands/changelog.js @@ -22,21 +22,24 @@ const manifest = require( '../../../package.json' ); /** @typedef {import('@octokit/rest')} GitHub */ /** @typedef {import('@octokit/rest').IssuesListForRepoResponseItem} IssuesListForRepoResponseItem */ /** @typedef {import('@octokit/rest').IssuesListMilestonesForRepoResponseItem} OktokitIssuesListMilestonesForRepoResponseItem */ +/** @typedef {import('@octokit/rest').ReposListReleasesResponseItem} ReposListReleasesResponseItem */ /** * @typedef WPChangelogCommandOptions * - * @property {string=} milestone Optional Milestone title. - * @property {string=} token Optional personal access token. + * @property {string=} milestone Optional Milestone title. + * @property {string=} token Optional personal access token. + * @property {boolean=} unreleased Optional flag to only include issues that haven't been part of a release yet. */ /** * @typedef WPChangelogSettings * - * @property {string} owner Repository owner. - * @property {string} repo Repository name. - * @property {string=} token Optional personal access token. - * @property {string} milestone Milestone title. + * @property {string} owner Repository owner. + * @property {string} repo Repository name. + * @property {string=} token Optional personal access token. + * @property {string} milestone Milestone title. + * @property {boolean=} unreleased Only include issues that have been closed since the milestone's latest release. */ /** @@ -47,20 +50,51 @@ const manifest = require( '../../../package.json' ); */ /** - * Mapping of label names to grouping heading text to be used in release notes, - * intended to be more readable in the context of release notes. Also used in - * merging multiple related groupings to a single heading. + * Mapping of label names to sections in the release notes. + * + * Labels are sorted by the priority they have when there are + * multiple candidates. For example, if an issue has the labels + * "[Block] Navigation" and "[Type] Bug", it'll be assigned the + * section declared by "[Block] Navigation". * * @type {Record} */ const LABEL_TYPE_MAPPING = { - Bug: 'Bug Fixes', - Regression: 'Bug Fixes', - Feature: 'Features', - Enhancement: 'Enhancements', - 'New API': 'New APIs', - Experimental: 'Experiments', - Task: 'Various', + '[Block] Navigation': 'Experiments', + '[Block] Query': 'Experiments', + '[Block] Post Comments Count': 'Experiments', + '[Block] Post Comments Form': 'Experiments', + '[Block] Post Comments': 'Experiments', + '[Block] Post Featured Image': 'Experiments', + '[Block] Post Hierarchical Terms': 'Experiments', + '[Block] Post Title': 'Experiments', + '[Block] Site Logo': 'Experiments', + '[Feature] Full Site Editing': 'Experiments', + 'Global Styles': 'Experiments', + '[Feature] Navigation Screen': 'Experiments', + '[Feature] Widgets Screen': 'Experiments', + '[Package] Dependency Extraction Webpack Plugin': 'Tools', + '[Package] Jest Puppeteer aXe': 'Tools', + '[Package] E2E Tests': 'Tools', + '[Package] E2E Test Utils': 'Tools', + '[Package] Env': 'Tools', + '[Package] ESLint plugin': 'Tools', + '[Package] stylelint config': 'Tools', + '[Package] Project management automation': 'Tools', + '[Type] Project Management': 'Tools', + '[Package] Scripts': 'Tools', + '[Type] Build Tooling': 'Tools', + 'Automated Testing': 'Tools', + '[Type] Experimental': 'Experiments', + '[Type] Bug': 'Bug Fixes', + '[Type] Regression': 'Bug Fixes', + '[Type] Feature': 'Features', + '[Type] Enhancement': 'Enhancements', + '[Type] New API': 'New APIs', + '[Type] Performance': 'Performance', + '[Type] Documentation': 'Documentation', + '[Type] Code Quality': 'Code Quality', + '[Type] Security': 'Security', }; /** @@ -78,6 +112,7 @@ const GROUP_TITLE_ORDER = [ 'Experiments', 'Documentation', 'Code Quality', + 'Tools', undefined, 'Various', ]; @@ -105,7 +140,8 @@ const REWORD_TERMS = { }; /** - * Returns type candidates based on given issue label names. + * Returns candidates based on whether the given labels + * are part of the allowed list. * * @param {string[]} labels Label names. * @@ -114,13 +150,10 @@ const REWORD_TERMS = { function getTypesByLabels( labels ) { return uniq( labels - .filter( ( label ) => label.startsWith( '[Type] ' ) ) - .map( ( label ) => label.slice( '[Type] '.length ) ) - .map( ( label ) => - LABEL_TYPE_MAPPING.hasOwnProperty( label ) - ? LABEL_TYPE_MAPPING[ label ] - : label + .filter( ( label ) => + Object.keys( LABEL_TYPE_MAPPING ).includes( label ) ) + .map( ( label ) => LABEL_TYPE_MAPPING[ label ] ) ); } @@ -151,12 +184,29 @@ function getTypesByTitle( title ) { * @return {string} Type label. */ function getIssueType( issue ) { + const labels = issue.labels.map( ( { name } ) => name ); const candidates = [ - ...getTypesByLabels( issue.labels.map( ( { name } ) => name ) ), + ...getTypesByLabels( labels ), ...getTypesByTitle( issue.title ), ]; - return candidates.length ? candidates.sort( sortGroup )[ 0 ] : 'Various'; + return candidates.length ? candidates.sort( sortType )[ 0 ] : 'Various'; +} + +/** + * Sort comparator, comparing two label candidates. + * + * @param {string} a First candidate. + * @param {string} b Second candidate. + * + * @return {number} Sort result. + */ +function sortType( a, b ) { + const [ aIndex, bIndex ] = [ a, b ].map( ( title ) => { + return Object.keys( LABEL_TYPE_MAPPING ).indexOf( title ); + } ); + + return aIndex - bIndex; } /** @@ -287,11 +337,8 @@ function removeRedundantTypePrefix( title, issue ) { * @type {Array} */ const TITLE_NORMALIZATIONS = [ - createOmitByTitlePrefix( [ '[rnmobile]' ] ), - createOmitByLabel( [ - 'Mobile App Compatibility', - '[Type] Project Management', - ] ), + createOmitByLabel( [ 'Mobile App Android/iOS' ] ), + createOmitByTitlePrefix( [ '[rnmobile]', '[mobile]', 'Mobile Release' ] ), removeRedundantTypePrefix, reword, capitalizeAfterColonSeparatedPrefix, @@ -336,6 +383,43 @@ function getEntry( issue ) { : `- ${ title } ([${ issue.number }](${ issue.html_url }))`; } +/** + * Returns the latest release for a given series + * + * @param {GitHub} octokit Initialized Octokit REST client. + * @param {string} owner Repository owner. + * @param {string} repo Repository name. + * @param {string} series Gutenberg release series (e.g. '6.7' or '9.8'). + * + * @return {Promise} Promise resolving to pull + * requests for the given + * milestone. + */ +async function getLatestReleaseInSeries( octokit, owner, repo, series ) { + const releaseOptions = await octokit.repos.listReleases.endpoint.merge( { + owner, + repo, + } ); + + let latestReleaseForMilestone; + + /** + * @type {AsyncIterableIterator>} + */ + const releases = octokit.paginate.iterator( releaseOptions ); + + for await ( const releasesPage of releases ) { + latestReleaseForMilestone = releasesPage.data.find( ( release ) => + release.name.startsWith( series ) + ); + + if ( latestReleaseForMilestone ) { + return latestReleaseForMilestone; + } + } + return undefined; +} + /** * Returns a promise resolving to an array of pull requests associated with the * changelog settings object. @@ -347,7 +431,7 @@ function getEntry( issue ) { * pull requests. */ async function fetchAllPullRequests( octokit, settings ) { - const { owner, repo, milestone: milestoneTitle } = settings; + const { owner, repo, milestone: milestoneTitle, unreleased } = settings; const milestone = await getMilestoneByTitle( octokit, owner, @@ -361,13 +445,19 @@ async function fetchAllPullRequests( octokit, settings ) { ); } + const series = milestoneTitle.replace( 'Gutenberg ', '' ); + const latestReleaseInSeries = unreleased + ? await getLatestReleaseInSeries( octokit, owner, repo, series ) + : undefined; + const { number } = milestone; const issues = await getIssuesByMilestone( octokit, owner, repo, number, - 'closed' + 'closed', + latestReleaseInSeries ? latestReleaseInSeries.published_at : undefined ); return issues.filter( ( issue ) => issue.pull_request ); } @@ -386,9 +476,15 @@ async function getChangelog( settings ) { const pullRequests = await fetchAllPullRequests( octokit, settings ); if ( ! pullRequests.length ) { - throw new Error( - 'There are no pull requests associated with the milestone.' - ); + if ( settings.unreleased ) { + throw new Error( + 'There are no unreleased pull requests associated with the milestone.' + ); + } else { + throw new Error( + 'There are no pull requests associated with the milestone.' + ); + } } let changelog = ''; @@ -458,6 +554,7 @@ async function getReleaseChangelog( options ) { ), } ) : options.milestone, + unreleased: options.unreleased, } ); } diff --git a/bin/plugin/commands/common.js b/bin/plugin/commands/common.js index 5a300e50e68c2c..57326be7205bfd 100644 --- a/bin/plugin/commands/common.js +++ b/bin/plugin/commands/common.js @@ -66,12 +66,10 @@ async function runCleanLocalFoldersStep( folders, abortMessage ) { * @return {string} Name of the release branch. */ function findReleaseBranchName( packageJsonPath ) { - const masterPackageJson = readJSONFile( packageJsonPath ); - const masterParsedVersion = semver.parse( masterPackageJson.version ); + const mainPackageJson = readJSONFile( packageJsonPath ); + const mainParsedVersion = semver.parse( mainPackageJson.version ); - return ( - 'release/' + masterParsedVersion.major + '.' + masterParsedVersion.minor - ); + return 'release/' + mainParsedVersion.major + '.' + mainParsedVersion.minor; } /** diff --git a/bin/plugin/commands/packages.js b/bin/plugin/commands/packages.js index 6291008ae575af..2b9a46ab3f758d 100644 --- a/bin/plugin/commands/packages.js +++ b/bin/plugin/commands/packages.js @@ -1,6 +1,7 @@ /** * External dependencies */ +const { command } = require( 'execa' ); const path = require( 'path' ); const glob = require( 'fast-glob' ); const fs = require( 'fs' ); @@ -32,15 +33,17 @@ const git = require( '../lib/git' ); * the last plugin release. * * @param {string} gitWorkingDirectoryPath Git working directory path. + * @param {boolean} isPrerelease Whether the package version to publish is a prerelease. * @param {string} abortMessage Abort Message. * * @return {Promise} WordPress release branch. */ async function runWordPressReleaseBranchSyncStep( gitWorkingDirectoryPath, + isPrerelease, abortMessage ) { - const wordpressReleaseBranch = 'wp/trunk'; + const wordpressReleaseBranch = isPrerelease ? 'wp/next' : 'wp/trunk'; await runStep( 'Getting into the WordPress release branch', abortMessage, @@ -108,8 +111,22 @@ async function updatePackages( const changelogFiles = await glob( path.resolve( gitWorkingDirectoryPath, 'packages/*/CHANGELOG.md' ) ); + const changelogFilesPublicPackages = changelogFiles.filter( + ( changelogPath ) => { + const pkg = require( path.join( + path.dirname( changelogPath ), + 'package.json' + ) ); + return pkg.private !== true; + } + ); + + const productionPackageNames = Object.keys( + require( '../../../package.json' ).dependencies + ); + const processedPackages = await Promise.all( - changelogFiles.map( async ( changelogPath ) => { + changelogFilesPublicPackages.map( async ( changelogPath ) => { const fileStream = fs.createReadStream( changelogPath ); const rl = readline.createInterface( { @@ -120,13 +137,23 @@ async function updatePackages( lines.push( line ); } - const versionBump = calculateVersionBumpFromChangelog( + let versionBump = calculateVersionBumpFromChangelog( lines, minimumVersionBump ); const packageName = `@wordpress/${ changelogPath.split( '/' ).reverse()[ 1 ] }`; + // Enforce version bump for production packages when + // the stable minor or major version bump requested. + if ( + ! versionBump && + ! isPrerelease && + minimumVersionBump !== 'patch' && + productionPackageNames.includes( packageName ) + ) { + versionBump = minimumVersionBump; + } const packageJSONPath = changelogPath.replace( 'CHANGELOG.md', 'package.json' @@ -180,7 +207,7 @@ async function updatePackages( content.replace( '## Unreleased', `## Unreleased\n\n## ${ - isPrerelease ? nextVersion + '-rc.0' : nextVersion + isPrerelease ? nextVersion + '-next.0' : nextVersion } (${ publishDate })` ) ); @@ -197,7 +224,9 @@ async function updatePackages( ); log( - ` - ${ packageName }: ${ version } -> ${ nextVersion }` + ` - ${ packageName }: ${ version } -> ${ + isPrerelease ? nextVersion + '-next.0' : nextVersion + }` ); } ) @@ -242,6 +271,61 @@ async function runPushGitChangesStep( ); } +/** + * Publishes all changed packages to npm. + * + * @param {string} gitWorkingDirectoryPath Git working directory path. + * @param {SemVer} minimumVersionBump Minimum version bump for the packages. + * @param {boolean} isPrerelease Whether the package version to publish is a prerelease. + */ +async function publishPackagesToNpm( + gitWorkingDirectoryPath, + minimumVersionBump, + isPrerelease +) { + log( '>> Installing npm packages.' ); + await command( 'npm ci', { + cwd: gitWorkingDirectoryPath, + } ); + + if ( isPrerelease ) { + log( + '>> Bumping version of public packages changed since the last release.' + ); + const { stdout: sha } = await command( 'git rev-parse --short HEAD' ); + await command( + `npx lerna version pre${ minimumVersionBump } --preid next.${ sha } --no-private`, + { + cwd: gitWorkingDirectoryPath, + stdio: 'inherit', + } + ); + + log( '>> Publishing modified packages to npm.' ); + await command( 'npx lerna publish from-package --dist-tag next', { + cwd: gitWorkingDirectoryPath, + stdio: 'inherit', + } ); + } else { + log( + '>> Bumping version of public packages changed since the last release.' + ); + await command( + `npx lerna version ${ minimumVersionBump } --no-private`, + { + cwd: gitWorkingDirectoryPath, + stdio: 'inherit', + } + ); + + log( '>> Publishing modified packages to npm.' ); + await command( `npx lerna publish from-package`, { + cwd: gitWorkingDirectoryPath, + stdio: 'inherit', + } ); + } +} + /** * Prepare everything to publish WordPress packages to npm. * @@ -250,20 +334,20 @@ async function runPushGitChangesStep( * @return {Promise} Github release object. */ async function prepareForPackageRelease( isPrerelease ) { - // This is a variable that contains the abort message shown when the script is aborted. - let abortMessage = 'Aborting!'; - const temporaryFolders = []; - await askForConfirmation( 'Ready to go? ' ); + await askForConfirmation( 'Ready to go?' ); // Cloning the Git repository. + const abortMessage = 'Aborting!'; const gitWorkingDirectoryPath = await runGitRepositoryCloneStep( abortMessage ); + const temporaryFolders = []; temporaryFolders.push( gitWorkingDirectoryPath ); // Checking out the WordPress release branch and doing sync with the last plugin release. const { releaseBranch } = await runWordPressReleaseBranchSyncStep( gitWorkingDirectoryPath, + isPrerelease, abortMessage ); @@ -284,58 +368,59 @@ async function prepareForPackageRelease( isPrerelease ) { abortMessage ); - // Push the local changes - abortMessage = `Aborting! Make sure to push changes applied to WordPress release branch "${ releaseBranch }" manually.`; await runPushGitChangesStep( gitWorkingDirectoryPath, releaseBranch, - abortMessage + `Aborting! Make sure to push changes applied to WordPress release branch "${ releaseBranch }" manually.` + ); + + await publishPackagesToNpm( + gitWorkingDirectoryPath, + minimumVersionBump, + isPrerelease ); - abortMessage = 'Aborting! The release is finished though.'; - await runCleanLocalFoldersStep( temporaryFolders, abortMessage ); + await runCleanLocalFoldersStep( temporaryFolders, 'Cleaning failed.' ); } /** - * Prepares everything for publishing a new stable version of WordPress packages. + * Publishes a new latest version of WordPress packages. */ -async function prepareLatestDistTag() { +async function publishNpmLatestDistTag() { log( formats.title( '\n💃 Time to publish WordPress packages to npm 🕺\n\n' ), - 'Welcome! This tool is going to help you with preparing everything for publishing a new stable version of WordPress packages.\n', + 'Welcome! This tool is going to help you with publishing a new latest version of WordPress packages.\n', "To perform a release you'll have to be a member of the WordPress Team on npm.\n" ); await prepareForPackageRelease(); log( - '\n>> 🎉 WordPress packages are ready to publish!\n', - 'You need to run "npm run publish:prod" to release them to npm.\n', - 'Let also people know on WordPress Slack when everything is finished.\n' + '\n>> 🎉 WordPress packages are now published!\n', + 'Let also people know on WordPress Slack.\n' ); } /** - * Prepares everything for publishing a new RC version of WordPress packages. + * Publishes a new next version of WordPress packages. */ -async function prepareNextDistTag() { +async function publishNpmNextDistTag() { log( formats.title( '\n💃 Time to publish WordPress packages to npm 🕺\n\n' ), - 'Welcome! This tool is going to help you with preparing everything for publishing a new RC version of WordPress packages.\n', + 'Welcome! This tool is going to help you with publishing a new next version of WordPress packages.\n', "To perform a release you'll have to be a member of the WordPress Team on npm.\n" ); await prepareForPackageRelease( true ); log( - '\n>> 🎉 WordPress packages are ready to publish!\n', - 'You need to run "npm run publish:dev" to release them to npm.\n', - 'Let also people know on WordPress Slack when everything is finished.\n' + '\n>> 🎉 WordPress packages are now published!\n', + 'Let also people know on WordPress Slack.\n' ); } -module.exports = { prepareLatestDistTag, prepareNextDistTag }; +module.exports = { publishNpmLatestDistTag, publishNpmNextDistTag }; diff --git a/bin/plugin/commands/performance.js b/bin/plugin/commands/performance.js index 22f7f2e7eade47..b6bea97a459e51 100644 --- a/bin/plugin/commands/performance.js +++ b/bin/plugin/commands/performance.js @@ -148,7 +148,7 @@ async function setUpGitBranch( branch, environmentDirectory ) { log( '>> Building the ' + formats.success( branch ) + ' branch' ); await runShellScript( - 'rm -rf node_modules && npm install && npm run build', + 'rm -rf node_modules packages/*/node_modules && npm install && npm run build', environmentDirectory ); } @@ -205,13 +205,13 @@ async function runTestSuite( testSuite, performanceTestDirectory ) { /** * Runs the performances tests on an array of branches and output the result. * - * @param {WPPerformanceCommandOptions} options Command options. * @param {string[]} branches Branches to compare + * @param {WPPerformanceCommandOptions} options Command options. */ async function runPerformanceTests( branches, options ) { // The default value doesn't work because commander provides an array. if ( branches.length === 0 ) { - branches = [ 'master' ]; + branches = [ 'trunk' ]; } log( @@ -262,7 +262,7 @@ async function runPerformanceTests( branches, options ) { log( '>> Starting the WordPress environment' ); await runShellScript( 'npm run wp-env start', environmentDirectory ); - const testSuites = [ 'post-editor', 'site-editor' ]; + const testSuites = [ 'post-editor', 'i18n-filters', 'site-editor' ]; /** @type {Record>} */ let results = {}; diff --git a/bin/plugin/commands/release.js b/bin/plugin/commands/release.js index 56a232d13882c4..a554ac42f1288d 100644 --- a/bin/plugin/commands/release.js +++ b/bin/plugin/commands/release.js @@ -11,14 +11,8 @@ const { sprintf } = require( 'sprintf-js' ); * Internal dependencies */ const { log, formats } = require( '../lib/logger' ); -const { - askForConfirmation, - runStep, - readJSONFile, - runShellScript, -} = require( '../lib/utils' ); +const { askForConfirmation, runStep, readJSONFile } = require( '../lib/utils' ); const git = require( '../lib/git' ); -const svn = require( '../lib/svn' ); const { getNextMajorVersion } = require( '../lib/version' ); const { getIssuesByMilestone, @@ -31,31 +25,6 @@ const { findReleaseBranchName, } = require( './common' ); -const STABLE_TAG_REGEX = /Stable tag: [0-9]+\.[0-9]+\.[0-9]+\s*\n/; -const STABLE_TAG_PLACEHOLDER = 'Stable tag: V.V.V\n'; - -/** - * Fetching the SVN repository to the working directory. - * - * @param {string} abortMessage Abort message. - * - * @return {Promise} Repository local path. - */ -async function runSvnRepositoryCheckoutStep( abortMessage ) { - // Cloning the repository - let svnWorkingDirectoryPath; - await runStep( 'Fetching the SVN repository', abortMessage, async () => { - log( '>> Fetching the SVN repository' ); - svnWorkingDirectoryPath = svn.checkout( config.svnRepositoryURL ); - log( - '>> The SVN repository has been successfully fetched in the following temporary folder: ' + - formats.success( svnWorkingDirectoryPath ) - ); - } ); - - return svnWorkingDirectoryPath; -} - /** * Creates a new release branch based on the last package.json version * and chooses the next version number. @@ -190,7 +159,7 @@ async function runBumpPluginVersionUpdateChangelogAndCommitStep( readmeFileContent.indexOf( '== Changelog ==' ) ) + '== Changelog ==\n\n' + - `To read the changelog for ${ config.name } ${ version }, please navigate to the release page.` + + `To read the changelog for ${ config.name } ${ version }, please navigate to the release page.` + '\n'; fs.writeFileSync( readmePath, newReadmeContent ); @@ -245,35 +214,6 @@ async function runBumpPluginVersionUpdateChangelogAndCommitStep( return commitHash; } -/** - * Run the Plugin ZIP Creation step. - * - * @param {string} gitWorkingDirectoryPath Git Working Directory Path. - * @param {string} abortMessage Abort message. - * - * @return {Promise} Plugin ZIP Path - */ -async function runPluginZIPCreationStep( - gitWorkingDirectoryPath, - abortMessage -) { - const zipPath = gitWorkingDirectoryPath + '/' + config.slug + '.zip'; - await runStep( 'Plugin ZIP creation', abortMessage, async () => { - await askForConfirmation( - 'Proceed and build the plugin ZIP? (It takes a few minutes)', - true, - abortMessage - ); - runShellScript( config.buildZipCommand, gitWorkingDirectoryPath ); - log( - '>> The plugin ZIP has been built successfully. Path: ' + - formats.success( zipPath ) - ); - } ); - - return zipPath; -} - /** * Create a local Git Tag. * @@ -336,272 +276,37 @@ async function runPushGitChangesStep( } /** - * Cherry-picks the version bump commit into master. + * Cherry-picks the version bump commit into trunk. * * @param {string} gitWorkingDirectoryPath Git Working Directory Path. * @param {string} commitHash Commit to cherry-pick. * @param {string} abortMessage Abort message. */ -async function runCherrypickBumpCommitIntoMasterStep( +async function runCherrypickBumpCommitIntoTrunkStep( gitWorkingDirectoryPath, commitHash, abortMessage ) { await runStep( - 'Cherry-picking the bump commit into master', + 'Cherry-picking the bump commit into trunk', abortMessage, async () => { await askForConfirmation( - 'The plugin is now released. Proceed with the version bump in the master branch?', + 'The plugin is now released. Proceed with the version bump in the trunk branch?', true, abortMessage ); await git.discardLocalChanges( gitWorkingDirectoryPath ); await git.resetLocalBranchAgainstOrigin( gitWorkingDirectoryPath, - 'master' + 'trunk' ); await git.cherrypickCommitIntoBranch( gitWorkingDirectoryPath, commitHash, - 'master' - ); - await git.pushBranchToOrigin( gitWorkingDirectoryPath, 'master' ); - } - ); -} - -/** - * Creates the github release and uploads the ZIP file into it. - * - * @param {string} zipPath Plugin zip path. - * @param {string} version Released version. - * @param {string} versionLabel Label of the released Version. - * @param {string} changelog Release changelog. - * @param {boolean} isPrerelease is a pre-release. - * @param {string} abortMessage Abort message. - * - * @return {Promise} Github release object. - */ -async function runGithubReleaseStep( - zipPath, - version, - versionLabel, - changelog, - isPrerelease, - abortMessage -) { - let octokit; - let releaseDraft; - let release; - - await runStep( - 'Creating the GitHub release draft', - abortMessage, - async () => { - await askForConfirmation( - 'Proceed with the creation of the GitHub release draft?', - true, - abortMessage - ); - - const { token } = await inquirer.prompt( [ - { - type: 'input', - name: 'token', - message: - 'Please enter a GitHub personal authentication token.\n' + - 'You can create one by navigating to ' + - formats.success( - 'https://github.com/settings/tokens/new?scopes=repo,admin:org,write:packages' - ) + - '.\nToken:', - }, - ] ); - - octokit = new Octokit( { - auth: token, - } ); - - const releaseDraftData = await octokit.repos.createRelease( { - owner: config.githubRepositoryOwner, - repo: config.githubRepositoryName, - tag_name: 'v' + version, - name: versionLabel, - body: changelog, - prerelease: isPrerelease, - draft: true, - } ); - releaseDraft = releaseDraftData.data; - - log( '>> The GitHub release draft has been created.' ); - } - ); - abortMessage = - abortMessage + - ' Make sure to remove the the GitHub release draft as well.'; - - // Uploading the Zip to the Github release - await runStep( 'Uploading the plugin ZIP', abortMessage, async () => { - const filestats = fs.statSync( zipPath ); - await octokit.repos.uploadReleaseAsset( { - url: releaseDraft.upload_url, - headers: { - 'content-length': filestats.size, - 'content-type': 'application/zip', - }, - name: config.slug + '.zip', - file: fs.createReadStream( zipPath ), - } ); - log( '>> The plugin ZIP has been successfully uploaded.' ); - } ); - - // Remove draft status from the Github release - await runStep( 'Publishing the Github release', abortMessage, async () => { - const releaseData = await octokit.repos.updateRelease( { - owner: config.githubRepositoryOwner, - repo: config.githubRepositoryName, - release_id: releaseDraft.id, - draft: false, - } ); - release = releaseData.data; - - log( '>> The GitHub release has been published.' ); - } ); - - log( - '>> The GitHub release is available here: ' + - formats.success( release.html_url ) - ); - - return release; -} - -/** - * Updates and commits the content of the SVN repo using the new plugin ZIP. - * - * @param {string} svnWorkingDirectoryPath SVN Working Directory Path. - * @param {string} zipPath Plugin zip path. - * @param {string} version Version. - * @param {string} abortMessage Abort Message. - */ -async function runUpdateTrunkContentStep( - svnWorkingDirectoryPath, - zipPath, - version, - abortMessage -) { - // Updating the content of the svn - await runStep( 'Updating trunk content', abortMessage, async () => { - log( '>> Replacing trunk content using the new plugin ZIP' ); - - const readmePath = svnWorkingDirectoryPath + '/readme.txt'; - - const previousReadmeFileContent = fs.readFileSync( readmePath, 'utf8' ); - const stableTag = previousReadmeFileContent.match( - STABLE_TAG_REGEX - )[ 0 ]; - - // Delete everything - runShellScript( - 'find . -maxdepth 1 -not -name ".svn" -not -name "." -not -name ".." -exec rm -rf {} +', - svnWorkingDirectoryPath - ); - - // Update the content using the plugin ZIP - runShellScript( 'unzip ' + zipPath + ' -d ' + svnWorkingDirectoryPath ); - - // Replace the stable tag placeholder with the existing stable tag on the SVN repository. - const newReadmeFileContent = fs.readFileSync( readmePath, 'utf8' ); - fs.writeFileSync( - readmePath, - newReadmeFileContent.replace( STABLE_TAG_PLACEHOLDER, stableTag ) - ); - - // Commit the content changes - runShellScript( - "svn st | grep '^?' | awk '{print $2}' | xargs svn add", - svnWorkingDirectoryPath - ); - runShellScript( - "svn st | grep '^!' | awk '{print $2}' | xargs svn rm", - svnWorkingDirectoryPath - ); - await askForConfirmation( - 'Trunk content has been updated, please check the SVN diff. Commit the changes?', - true, - abortMessage - ); - - svn.commit( svnWorkingDirectoryPath, 'Committing version ' + version ); - log( '>> Trunk has been successfully updated' ); - } ); -} - -/** - * Creates a new SVN Tag - * - * @param {string} version Version. - * @param {string} abortMessage Abort Message. - */ -async function runSvnTagStep( version, abortMessage ) { - await runStep( 'Creating the SVN Tag', abortMessage, async () => { - await askForConfirmation( - 'Proceed with the creation of the SVN Tag?', - true, - abortMessage - ); - svn.tagTrunk( - config.svnRepositoryURL, - version, - 'Tagging version ' + version - ); - log( - '>> The SVN ' + - formats.success( version ) + - ' tag has been successfully created' - ); - } ); -} - -/** - * Updates the stable version of the plugin in the SVN repository. - * - * @param {string} svnWorkingDirectoryPath SVN working directory. - * @param {string} version Version. - * @param {string} abortMessage Abort Message. - */ -async function updateThePluginStableVersion( - svnWorkingDirectoryPath, - version, - abortMessage -) { - // Updating the content of the svn - await runStep( - "Updating the plugin's stable version", - abortMessage, - async () => { - const readmePath = svnWorkingDirectoryPath + '/readme.txt'; - const readmeFileContent = fs.readFileSync( readmePath, 'utf8' ); - const newReadmeContent = readmeFileContent.replace( - STABLE_TAG_REGEX, - 'Stable tag: ' + version + '\n' + 'trunk' ); - fs.writeFileSync( readmePath, newReadmeContent ); - - // Commit the content changes - await askForConfirmation( - 'The stable version is updated in the readme.txt file. Commit the changes?', - true, - abortMessage - ); - - svn.commit( - svnWorkingDirectoryPath, - 'Releasing version ' + version - ); - - log( '>> Stable version updated successfully' ); + await git.pushBranchToOrigin( gitWorkingDirectoryPath, 'trunk' ); } ); } @@ -655,7 +360,7 @@ async function isMilestoneClear( version ) { * * @param {boolean} isRC Whether it's an RC release or not. * - * @return {Promise} Github release object. + * @return {string} The new version. */ async function releasePlugin( isRC = true ) { // This is a variable that contains the abort message shown when the script is aborted. @@ -728,8 +433,6 @@ async function releasePlugin( isRC = true ) { ); } - const versionLabel = version.replace( /\-rc\.([0-9]+)/, ' RC$1' ); - if ( ! ( await isMilestoneClear( version ) ) ) { await askForConfirmation( 'There are still open issues in the milestone. Are you sure you want to proceed?', @@ -746,12 +449,6 @@ async function releasePlugin( isRC = true ) { abortMessage ); - // Plugin ZIP creation - const zipPath = await runPluginZIPCreationStep( - gitWorkingDirectory, - abortMessage - ); - // Creating the git tag await runCreateGitTagStep( gitWorkingDirectory, version, abortMessage ); @@ -762,101 +459,44 @@ async function releasePlugin( isRC = true ) { abortMessage ); - abortMessage = - 'Aborting! Make sure to ' + - ( isRC ? 'remove' : 'reset' ) + - ' the remote release branch and remove the git tag.'; - - // Creating the GitHub Release - const release = await runGithubReleaseStep( - zipPath, - version, - versionLabel, - changelog, - isRC, - abortMessage - ); - abortMessage = 'Aborting! Make sure to manually cherry-pick the ' + formats.success( commitHash ) + - ' commit to the master branch.'; - if ( ! isRC ) { - abortMessage += - ' Make sure to perform the SVN release manually as well.'; - } + ' commit to the trunk branch.'; - // Cherry-picking the bump commit into master - await runCherrypickBumpCommitIntoMasterStep( + // Cherry-picking the bump commit into trunk + await runCherrypickBumpCommitIntoTrunkStep( gitWorkingDirectory, commitHash, abortMessage ); - if ( ! isRC ) { - abortMessage = - 'Aborting! The GitHub release is done. Make sure to perform the SVN release manually.'; - - await askForConfirmation( - 'The GitHub release is complete. Proceed with the SVN release? ', - true, - abortMessage - ); - - // Fetching the SVN repository - const svnWorkingDirectory = await runSvnRepositoryCheckoutStep( - abortMessage - ); - temporaryFolders.push( svnWorkingDirectory ); - - // Updating the SVN trunk content - await runUpdateTrunkContentStep( - svnWorkingDirectory, - zipPath, - version, - abortMessage - ); - - abortMessage = - 'Aborting! The GitHub release is done, SVN trunk updated. Make sure to create the SVN tag and update the stable version manually.'; - await runSvnTagStep( version, abortMessage ); - - abortMessage = - 'Aborting! The GitHub release is done, SVN tagged. Make sure to update the stable version manually.'; - await updateThePluginStableVersion( - svnWorkingDirectory, - version, - abortMessage - ); - } - abortMessage = 'Aborting! The release is finished though.'; await runCleanLocalFoldersStep( temporaryFolders, abortMessage ); - return release; + return version; } async function releaseRC() { log( formats.title( '\n💃 Time to release ' + config.name + ' 🕺\n\n' ), 'Welcome! This tool is going to help you release a new RC version of the Plugin.\n', - 'It goes through different steps: creating the release branch, bumping the plugin version, tagging and creating the GitHub release, building the ZIP...\n', - "To perform a release you'll have to be a member of the " + - config.team + - ' Team.\n' + 'It goes through different steps: creating the release branch, bumping the plugin version, tagging the release, and pushing the tag to GitHub.\n', + 'Once the tag is pushed to GitHub, GitHub will build the plugin ZIP, and attach it to a release draft.\n' ); - const release = await releasePlugin( true ); + const version = await releasePlugin( true ); log( '\n>> 🎉 The ' + config.name + ' version ' + - formats.success( release.name ) + - ' has been successfully released.\n', - 'You can access the GitHub release here: ' + - formats.success( release.html_url ) + + formats.success( version ) + + ' has been successfully tagged.\n', + "In a few minutes, you'll be able to find the GitHub release draft here: " + + formats.success( config.wpRepositoryReleasesURL ) + '\n', + "Don't forget to publish the release once the draft is available!\n", 'Thanks for performing the release!\n' ); } @@ -865,24 +505,33 @@ async function releaseStable() { log( formats.title( '\n💃 Time to release ' + config.name + ' 🕺\n\n' ), 'Welcome! This tool is going to help you release a new stable version of the Plugin.\n', - 'It goes through different steps: bumping the plugin version, tagging and creating the GitHub release, building the ZIP, pushing the release to the SVN repository...\n', - "To perform a release you'll have to be a member of the " + + 'It goes through different steps: bumping the plugin version, tagging the release, and pushing the tag to GitHub.\n', + 'Once the tag is pushed to GitHub, GitHub will build the plugin ZIP, and attach it to a release draft.\n', + 'To have the release uploaded to the WP.org plugin repository SVN, you need approval from a member of the ' + config.team + ' Team.\n' ); - const release = await releasePlugin( false ); + const version = await releasePlugin( false ); log( '\n>> 🎉 ' + config.name + ' ' + - formats.success( release.name ) + - ' has been successfully released.\n', - 'You can access the GitHub release here: ' + - formats.success( release.html_url ) + + formats.success( version ) + + ' has been successfully tagged.\n', + "In a few minutes, you'll be able to find the GitHub release draft here: " + + formats.success( config.wpRepositoryReleasesURL ) + '\n', - "In a few minutes, you'll be able to update the plugin from the WordPress repository.\n", + "Don't forget to publish the release once the draft is available!\n", + 'Once published, the upload to the WP.org plugin repository needs approval from a member of the ' + + config.team + + ' Team at ' + + formats.success( + config.githubRepositoryURL + + 'actions/workflows/upload-release-to-plugin-repo.yml ' + ) + + '.\n', "Thanks for performing the release! and don't forget to publish the release post.\n" ); } diff --git a/bin/plugin/commands/test/changelog.js b/bin/plugin/commands/test/changelog.js index 57a6082f9e9fa4..bdde2e92926c9f 100644 --- a/bin/plugin/commands/test/changelog.js +++ b/bin/plugin/commands/test/changelog.js @@ -33,16 +33,7 @@ describe( 'getNormalizedTitle', () => { undefined, { ...DEFAULT_ISSUE, - labels: [ { name: 'Mobile App Compatibility' } ], - }, - ], - [ - 'omits project management', - 'Add codeowner', - undefined, - { - ...DEFAULT_ISSUE, - labels: [ { name: '[Type] Project Management' } ], + labels: [ { name: 'Mobile App Android/iOS' } ], }, ], [ diff --git a/bin/plugin/config.js b/bin/plugin/config.js index e920af08cdc573..f045c10fdce34e 100644 --- a/bin/plugin/config.js +++ b/bin/plugin/config.js @@ -14,6 +14,7 @@ const gitRepoOwner = 'WordPress'; * @property {string} githubRepositoryName Github Repository Name. * @property {string} pluginEntryPoint Plugin Entry Point File. * @property {string} buildZipCommand Build Plugin ZIP command. + * @property {string} githubRepositoryURL GitHub Repository URL. * @property {string} wpRepositoryReleasesURL WordPress Repository Tags URL. * @property {string} gitRepositoryURL Git Repository URL. * @property {string} svnRepositoryURL SVN Repository URL. @@ -31,8 +32,8 @@ const config = { githubRepositoryName: 'gutenberg', pluginEntryPoint: 'gutenberg.php', buildZipCommand: '/bin/bash bin/build-plugin-zip.sh', - wpRepositoryReleasesURL: - 'https://github.com/WordPress/gutenberg/releases/tag/', + githubRepositoryURL: 'https://github.com/' + gitRepoOwner + '/gutenberg/', + wpRepositoryReleasesURL: 'https://github.com/WordPress/gutenberg/releases/', gitRepositoryURL: 'https://github.com/' + gitRepoOwner + '/gutenberg.git', svnRepositoryURL: 'https://plugins.svn.wordpress.org/gutenberg', }; diff --git a/bin/plugin/lib/git.js b/bin/plugin/lib/git.js index b8b4242800744f..52bb8118830df6 100644 --- a/bin/plugin/lib/git.js +++ b/bin/plugin/lib/git.js @@ -1,7 +1,8 @@ +// @ts-nocheck /** * External dependencies */ -const SimpleGit = require( 'simple-git/promise' ); +const SimpleGit = require( 'simple-git' ); /** * Internal dependencies @@ -125,7 +126,7 @@ async function resetLocalBranchAgainstOrigin( } /** - * Cherry-picks a commit into master + * Cherry-picks a commit into trunk * * @param {string} gitWorkingDirectoryPath Local repository path. * @param {string} commitHash Branch Name @@ -135,7 +136,7 @@ async function cherrypickCommitIntoBranch( commitHash ) { const simpleGit = SimpleGit( gitWorkingDirectoryPath ); - await simpleGit.checkout( 'master' ); + await simpleGit.checkout( 'trunk' ); await simpleGit.raw( [ 'cherry-pick', commitHash ] ); } diff --git a/bin/plugin/lib/milestone.js b/bin/plugin/lib/milestone.js index 8bd6cfbf0be723..88fae05e3b0c11 100644 --- a/bin/plugin/lib/milestone.js +++ b/bin/plugin/lib/milestone.js @@ -40,22 +40,33 @@ async function getMilestoneByTitle( octokit, owner, repo, title ) { /** * Returns a promise resolving to pull requests by a given milestone ID. * - * @param {GitHub} octokit Initialized Octokit REST client. - * @param {string} owner Repository owner. - * @param {string} repo Repository name. - * @param {number} milestone Milestone ID. - * @param {IssueState} [state] Optional issue state. + * @param {GitHub} octokit Initialized Octokit REST client. + * @param {string} owner Repository owner. + * @param {string} repo Repository name. + * @param {number} milestone Milestone ID. + * @param {IssueState} [state] Optional issue state. + * @param {string} [closedSince] Optional timestamp. * * @return {Promise} Promise resolving to pull * requests for the given * milestone. */ -async function getIssuesByMilestone( octokit, owner, repo, milestone, state ) { +async function getIssuesByMilestone( + octokit, + owner, + repo, + milestone, + state, + closedSince +) { const options = octokit.issues.listForRepo.endpoint.merge( { owner, repo, milestone, state, + ...( closedSince && { + since: closedSince, + } ), } ); /** @@ -63,6 +74,9 @@ async function getIssuesByMilestone( octokit, owner, repo, milestone, state ) { */ const responses = octokit.paginate.iterator( options ); + /** + * @type {import('@octokit/rest').IssuesListForRepoResponse} + */ const pulls = []; for await ( const response of responses ) { @@ -70,6 +84,24 @@ async function getIssuesByMilestone( octokit, owner, repo, milestone, state ) { pulls.push( ...issues ); } + if ( closedSince ) { + const closedSinceTimestamp = new Date( closedSince ); + + return pulls.filter( + ( pull ) => + pull.closed_at && + closedSinceTimestamp < + new Date( + // The ugly `as unknown as string` cast is required because of + // https://github.com/octokit/plugin-rest-endpoint-methods.js/issues/64 + // Fixed in Octokit v18.1.1, see https://github.com/WordPress/gutenberg/pull/29043 + /** @type {string} */ ( + /** @type {unknown} */ ( pull.closed_at ) + ) + ) + ); + } + return pulls; } diff --git a/bin/plugin/lib/svn.js b/bin/plugin/lib/svn.js deleted file mode 100644 index 533d7b7f0e2a0f..00000000000000 --- a/bin/plugin/lib/svn.js +++ /dev/null @@ -1,40 +0,0 @@ -/** - * Internal dependencies - */ -const { getRandomTemporaryPath, runShellScript } = require( './utils' ); - -function checkout( repositoryUrl ) { - const svnWorkingDirectoryPath = getRandomTemporaryPath(); - runShellScript( - 'svn checkout ' + repositoryUrl + '/trunk ' + svnWorkingDirectoryPath - ); - - return svnWorkingDirectoryPath; -} - -function commit( svnWorkingDirectoryPath, message ) { - runShellScript( - 'svn commit -m "' + message + '"', - svnWorkingDirectoryPath - ); -} - -function tagTrunk( repositoryUrl, tagName, message ) { - runShellScript( - 'svn cp ' + - repositoryUrl + - '/trunk ' + - repositoryUrl + - '/tags/' + - tagName + - ' -m "' + - message + - '"' - ); -} - -module.exports = { - checkout, - commit, - tagTrunk, -}; diff --git a/bin/test-create-block.sh b/bin/test-create-block.sh index e1073ce87d5162..6b1ea6842f9094 100755 --- a/bin/test-create-block.sh +++ b/bin/test-create-block.sh @@ -1,7 +1,7 @@ #!/bin/bash # This script validates whether `npm init @wordpress/block` works properly -# with the latest changes applied to the `master` branch. It purposefully +# with the latest changes applied to the `trunk` branch. It purposefully # avoids installing `@wordpress/scripts` package from npm when scaffolding # a test block and uses the local package by executing everything from the # root of the project. diff --git a/changelog.txt b/changelog.txt index cd4389cd59e70d..98900ed96f8597 100644 --- a/changelog.txt +++ b/changelog.txt @@ -1,5 +1,1090 @@ == Changelog == += 10.2.0-rc.1 = + +### Features + +- Template part block: Add category panel. ([29159](https://github.com/WordPress/gutenberg/pull/29159)) + +### Enhancements + +- Add check for button text before rendering button block. ([29717](https://github.com/WordPress/gutenberg/pull/29717)) +- Skip CSS minification via PHP. ([29624](https://github.com/WordPress/gutenberg/pull/29624)) +- Restore the margins of blocks relying on the figure element. ([29517](https://github.com/WordPress/gutenberg/pull/29517)) +- Add Columns transform from Media & Text. ([29415](https://github.com/WordPress/gutenberg/pull/29415)) +- Fix: Invert gallery gravity. ([29367](https://github.com/WordPress/gutenberg/pull/29367)) +- Components: Try to make the order of fills stable in regular slots. ([29287](https://github.com/WordPress/gutenberg/pull/29287)) +- Add expandOnFocus, showHowTo and validateInput experimental props to FormTokenField. ([29110](https://github.com/WordPress/gutenberg/pull/29110)) +- Hide writing prompt from subsequent empty paragraphs. ([28275](https://github.com/WordPress/gutenberg/pull/28275)) + +### New APIs + +- Plugins: Add scoping functionality to the Plugins API. ([27438](https://github.com/WordPress/gutenberg/pull/27438)) + +### Bug Fixes + +- Add theme styles in the site editor. ([29704](https://github.com/WordPress/gutenberg/pull/29704)) +- Fix broken links to the block editor developer handbook. ([29663](https://github.com/WordPress/gutenberg/pull/29663)) +- Yelp. ([29660](https://github.com/WordPress/gutenberg/pull/29660)) +- Fix social icons vertical spacing issue. ([29657](https://github.com/WordPress/gutenberg/pull/29657)) +- Fix in between inserter edge case. ([29625](https://github.com/WordPress/gutenberg/pull/29625)) +- Fix the button component styles when used with a dashicon. ([29614](https://github.com/WordPress/gutenberg/pull/29614)) +- Revert moving is-typing class. ([29608](https://github.com/WordPress/gutenberg/pull/29608)) +- Fix inline block styles minification issues with calc(). ([29554](https://github.com/WordPress/gutenberg/pull/29554)) +- Fix cover block content position not migrating correctly from deprecated version. ([29542](https://github.com/WordPress/gutenberg/pull/29542)) +- Fix solid-color only cover has small gray border in the editor only. ([29499](https://github.com/WordPress/gutenberg/pull/29499)) +- Table of Contents block: Fix links when in archive loop or when using "Plain" permalink structure. ([29394](https://github.com/WordPress/gutenberg/pull/29394)) +- Packages: Update the publishing command for npm with next dist tag. ([29379](https://github.com/WordPress/gutenberg/pull/29379)) +- Ignore build folders when native unit tests. ([29371](https://github.com/WordPress/gutenberg/pull/29371)) +- Fix mobile issue template label. ([29344](https://github.com/WordPress/gutenberg/pull/29344)) +- Interface: Fix React warnings triggered in ActionItem component. ([29340](https://github.com/WordPress/gutenberg/pull/29340)) +- Social Links: Replace CSS variables with block context approach. ([29330](https://github.com/WordPress/gutenberg/pull/29330)) +- Table of contents: Fix class attribute. ([29317](https://github.com/WordPress/gutenberg/pull/29317)) +- Search block: Add missing space to provide valid HTML. ([29314](https://github.com/WordPress/gutenberg/pull/29314)) +- Blocks: Ensure that metadata registered on the server for core block is preserved on the client (try 2). ([29302](https://github.com/WordPress/gutenberg/pull/29302)) +- Fix reusable block crash when converting a just created reusable block to blocks. ([29292](https://github.com/WordPress/gutenberg/pull/29292)) +- Fix off-center appender in some themes. ([29290](https://github.com/WordPress/gutenberg/pull/29290)) +- Fix legacy button center alignments inside the buttons block. ([29281](https://github.com/WordPress/gutenberg/pull/29281)) +- Add enableCustomSpacing to block editor settings. ([29277](https://github.com/WordPress/gutenberg/pull/29277)) +- Buttons: Fix links inside links. ([29273](https://github.com/WordPress/gutenberg/pull/29273)) +- Fix editor crash when converting block with visible styles to reusable (after a save and page reload). ([29059](https://github.com/WordPress/gutenberg/pull/29059)) +- Border Radius Support: Fix application of zero radius values. ([28998](https://github.com/WordPress/gutenberg/pull/28998)) +- Fix Document Outline mouse click. ([28589](https://github.com/WordPress/gutenberg/pull/28589)) + +### Performance + +- Revert "Block edit: Avoid memoized block context in favour of useSelect". ([29621](https://github.com/WordPress/gutenberg/pull/29621)) + +### Experiments + +- Global Styles: Do not add padding sub-properties if there's no values in theme.json. ([29712](https://github.com/WordPress/gutenberg/pull/29712)) +- Site Title: Add text decoration and text transform controls. ([29622](https://github.com/WordPress/gutenberg/pull/29622)) +- Make border work on the site editor. ([29618](https://github.com/WordPress/gutenberg/pull/29618)) +- i18n: Fix the template area unassigned type string. ([29617](https://github.com/WordPress/gutenberg/pull/29617)) +- Group Block: Add support for custom border settings. ([29591](https://github.com/WordPress/gutenberg/pull/29591)) +- Prevent clicking on tag and category links in the site editor. ([29583](https://github.com/WordPress/gutenberg/pull/29583)) +- Custom Link Color: Do not apply to buttons. ([29557](https://github.com/WordPress/gutenberg/pull/29557)) +- Navigation block: Allow very thin menus. ([29555](https://github.com/WordPress/gutenberg/pull/29555)) +- Fix specificity issue between theme and user styles. ([29533](https://github.com/WordPress/gutenberg/pull/29533)) +- Update template descriptions for clarity and humanity. ([29531](https://github.com/WordPress/gutenberg/pull/29531)) +- Print nothing in the front end if there are no results in Query block. ([29521](https://github.com/WordPress/gutenberg/pull/29521)) +- Pass block settings to the client for all blocks. ([29474](https://github.com/WordPress/gutenberg/pull/29474)) +- Refactor and simplify navigation block CSS. ([29465](https://github.com/WordPress/gutenberg/pull/29465)) +- [Query block] Remove exclusion of current page id. ([29432](https://github.com/WordPress/gutenberg/pull/29432)) +- Handle missing categories/tags in Query block. ([29424](https://github.com/WordPress/gutenberg/pull/29424)) +- Update title, description, and icon of Post Categories. ([29400](https://github.com/WordPress/gutenberg/pull/29400)) +- Button block: Add color support via block.json. ([29382](https://github.com/WordPress/gutenberg/pull/29382)) +- Global Styles: Fix specificity conflict of blocks with single classes as selectors. ([29378](https://github.com/WordPress/gutenberg/pull/29378)) +- Add/new nav link icon. ([29369](https://github.com/WordPress/gutenberg/pull/29369)) +- Make navigation placeholder state visible in dark themes. ([29366](https://github.com/WordPress/gutenberg/pull/29366)) +- Temporary hack to render blocks in customizer. ([29365](https://github.com/WordPress/gutenberg/pull/29365)) +- Show Site Logo's block toolbar when selected, after the editor loads. ([29336](https://github.com/WordPress/gutenberg/pull/29336)) +- Remove delete toolbar option from Site Logo. ([29331](https://github.com/WordPress/gutenberg/pull/29331)) +- Fix shortcode not showing in the widgets screen. ([29282](https://github.com/WordPress/gutenberg/pull/29282)) +- Implement skip serialization for color key in style att. ([29253](https://github.com/WordPress/gutenberg/pull/29253)) +- Update navigation editor menu selection dropdown. ([29202](https://github.com/WordPress/gutenberg/pull/29202)) +- Make Spacer block width adjustable and add it to Navigation block. ([29133](https://github.com/WordPress/gutenberg/pull/29133)) +- Navigation: Try adding navigation link variants via server. ([29095](https://github.com/WordPress/gutenberg/pull/29095)) +- Navigation Editor: Allow menu renaming. ([29012](https://github.com/WordPress/gutenberg/pull/29012)) +- Fix: More resilient appender CSS. ([28908](https://github.com/WordPress/gutenberg/pull/28908)) +- Query block setup with block patterns integration. ([28891](https://github.com/WordPress/gutenberg/pull/28891)) +- Template Part: Prevent infinite recursion. ([28456](https://github.com/WordPress/gutenberg/pull/28456)) + +### Documentation + +- Add block variations page to Block API summary. ([29725](https://github.com/WordPress/gutenberg/pull/29725)) +- Update Readme of Animate Component to remove todo comment. ([29702](https://github.com/WordPress/gutenberg/pull/29702)) +- Docs; Organize contributors section using READMEs. ([29688](https://github.com/WordPress/gutenberg/pull/29688)) +- Remove mid-paragraph newlines. ([29674](https://github.com/WordPress/gutenberg/pull/29674)) +- Update Versions in WordPress to include release notes. ([29532](https://github.com/WordPress/gutenberg/pull/29532)) +- Extract block variations API into its own handbook page. ([29515](https://github.com/WordPress/gutenberg/pull/29515)) +- Docs: Fix deprecation message to be clear. ([29451](https://github.com/WordPress/gutenberg/pull/29451)) +- Fix typo in block-based-themes.md. ([29410](https://github.com/WordPress/gutenberg/pull/29410)) +- Fix typo in modularity. ([29405](https://github.com/WordPress/gutenberg/pull/29405)) +- Fix typos in git workflow documentation. ([29324](https://github.com/WordPress/gutenberg/pull/29324)) +- Docs: Table of contents - fix typos. ([29319](https://github.com/WordPress/gutenberg/pull/29319)) +- Add NVDA instructions to the accessibility testing documentation. ([29312](https://github.com/WordPress/gutenberg/pull/29312)) +- Component Systems: Update references to external module. ([29233](https://github.com/WordPress/gutenberg/pull/29233)) +- Docs: Add info about npm release types and their schedule. ([29028](https://github.com/WordPress/gutenberg/pull/29028)) +- Docs: Update slug for block-based theme tutorial. ([25839](https://github.com/WordPress/gutenberg/pull/25839)) + +### Code Quality + +- Rename load_separate_block_styles to load_separate_block_assets. ([29703](https://github.com/WordPress/gutenberg/pull/29703)) +- Update the minimum WordPress version required by the gutenberg plugin too 5.6. ([29701](https://github.com/WordPress/gutenberg/pull/29701)) +- Components: Ensure that SlotFill does not use portals in React Native. ([29631](https://github.com/WordPress/gutenberg/pull/29631)) +- Remove the subheading block. ([29627](https://github.com/WordPress/gutenberg/pull/29627)) +- useFocusFirstElement: Include useRef. ([29435](https://github.com/WordPress/gutenberg/pull/29435)) +- Include PHP: Replace `dirname( __FILE__ )` with `__DIR__`. ([29404](https://github.com/WordPress/gutenberg/pull/29404)) +- Run phpcbf to fix PHP CS issues. ([29368](https://github.com/WordPress/gutenberg/pull/29368)) +- Register style attribute when any color property is supported. ([29349](https://github.com/WordPress/gutenberg/pull/29349)) +- Block edit: Avoid memoized block context in favour of useSelect. ([29333](https://github.com/WordPress/gutenberg/pull/29333)) +- Remove unused onFocus block context. ([29318](https://github.com/WordPress/gutenberg/pull/29318)) +- Remove obsolete block context. ([29313](https://github.com/WordPress/gutenberg/pull/29313)) +- Reduce memoized block context: Class names. ([29186](https://github.com/WordPress/gutenberg/pull/29186)) + +### Tools + +- Temporary skip flaky test. ([29601](https://github.com/WordPress/gutenberg/pull/29601)) +- Scripts: Fork jest-environment-puppeteer to use puppeteer-core directly. ([29418](https://github.com/WordPress/gutenberg/pull/29418)) +- Blocks: Preprocess validation log with util.format instead of sprintf. ([29334](https://github.com/WordPress/gutenberg/pull/29334)) +- Add stale issues bot to help triage efforts. ([29321](https://github.com/WordPress/gutenberg/pull/29321)) +- Do not automatically close message, update stale message. ([29310](https://github.com/WordPress/gutenberg/pull/29310)) +- Paragraph block: Add test to ensure unwrapped editable paragraph. ([29299](https://github.com/WordPress/gutenberg/pull/29299)) +- Testing: Use snapshot-diff serializer to remove noise in snapshots. ([29270](https://github.com/WordPress/gutenberg/pull/29270)) +- Inserter: Add end-to-end test to make sure last inserted block is being focused. ([29187](https://github.com/WordPress/gutenberg/pull/29187)) +- Docs: Update release.md. ([29091](https://github.com/WordPress/gutenberg/pull/29091)) +- Docs/Tools/CI: Update references from `master` to `trunk`. ([28433](https://github.com/WordPress/gutenberg/pull/28433)) +- Scripts: Add TypeScript support to linting command. ([27143](https://github.com/WordPress/gutenberg/pull/27143)) + +### Various + +- Add Table of Contents block (dynamic rendering + hooks version). ([21234](https://github.com/WordPress/gutenberg/pull/21234)) +- Deregister TOC block until issues are resolved. ([29718](https://github.com/WordPress/gutenberg/pull/29718)) +- api-fetch: Add incremental type checking. ([29685](https://github.com/WordPress/gutenberg/pull/29685)) +- docgen: Incrementally add types. ([29684](https://github.com/WordPress/gutenberg/pull/29684)) +- Dom: Add type-checking to data-transfer. ([29682](https://github.com/WordPress/gutenberg/pull/29682)) +- Template part 'area' term - reword confusing 'type' terminology. ([29679](https://github.com/WordPress/gutenberg/pull/29679)) +- Button Block: Removes "Link settings" panel. ([29664](https://github.com/WordPress/gutenberg/pull/29664)) +- Multi entity save panel - remove dynamic copy. ([29637](https://github.com/WordPress/gutenberg/pull/29637)) +- Components: Add types to Shortcut. ([29633](https://github.com/WordPress/gutenberg/pull/29633)) +- Add i18n support for template part variations' descriptions. ([29612](https://github.com/WordPress/gutenberg/pull/29612)) +- Add regression test for editor JS crash caused by rtlcss parsing exception, take 2. ([29598](https://github.com/WordPress/gutenberg/pull/29598)) +- Reset all WP Admin styles in the wrapper of the editor styles. ([29590](https://github.com/WordPress/gutenberg/pull/29590)) +- Revert "[Mobile] - Fix splitting/merging of Paragraph and Heading". ([29587](https://github.com/WordPress/gutenberg/pull/29587)) +- Try updating the minimum required WordPress version for the plugin. ([29579](https://github.com/WordPress/gutenberg/pull/29579)) +- Documents how the widgets editor works. ([29572](https://github.com/WordPress/gutenberg/pull/29572)) +- Drop zone: Fix media lib duplicate issue. ([29567](https://github.com/WordPress/gutenberg/pull/29567)) +- Update the category icons. ([29553](https://github.com/WordPress/gutenberg/pull/29553)) +- Try: Remove important on disabled switcher state. ([29552](https://github.com/WordPress/gutenberg/pull/29552)) +- Remove base control negative help text margin. ([29550](https://github.com/WordPress/gutenberg/pull/29550)) +- Navigation: Re-enable navigation block end-to-end tests. ([29543](https://github.com/WordPress/gutenberg/pull/29543)) +- Accessibility improvement on #29530 issue. ([29534](https://github.com/WordPress/gutenberg/pull/29534)) +- Components: Add TooltipButton. ([29523](https://github.com/WordPress/gutenberg/pull/29523)) +- Pin SHA values as version numbers for 3rd party GHAs. ([29485](https://github.com/WordPress/gutenberg/pull/29485)) +- Update the visual design of the Sidebar Menu. ([29476](https://github.com/WordPress/gutenberg/pull/29476)) +- Components: Update Elevation story. ([29454](https://github.com/WordPress/gutenberg/pull/29454)) +- Focus on block selection: Skip inner blocks. ([29434](https://github.com/WordPress/gutenberg/pull/29434)) +- Components: Add Divider. ([29433](https://github.com/WordPress/gutenberg/pull/29433)) +- Components: Add Tooltip and Shortcut. ([29385](https://github.com/WordPress/gutenberg/pull/29385)) +- Use correct classname for nested Navigation Link container. ([29380](https://github.com/WordPress/gutenberg/pull/29380)) +- Integrate AztecEditor-iOS 1.19.4. ([29355](https://github.com/WordPress/gutenberg/pull/29355)) +- Components: Add Card. ([29350](https://github.com/WordPress/gutenberg/pull/29350)) +- Components: Do not use ViewOwnProps for Portal. ([29345](https://github.com/WordPress/gutenberg/pull/29345)) +- Component System: Add basic tests for style system. ([29320](https://github.com/WordPress/gutenberg/pull/29320)) +- Block context: Separate native context. ([29315](https://github.com/WordPress/gutenberg/pull/29315)) +- Focus input when InputControl spinner arrows are pressed. ([29305](https://github.com/WordPress/gutenberg/pull/29305)) +- Component System: Add tests for color utils. ([29301](https://github.com/WordPress/gutenberg/pull/29301)) +- Template Part: Update switching trigger. ([29257](https://github.com/WordPress/gutenberg/pull/29257)) +- WP Block Styles: Only load in the editor if a theme opts in. ([29252](https://github.com/WordPress/gutenberg/pull/29252)) +- Components: Add next Button, ButtonGroup. ([29230](https://github.com/WordPress/gutenberg/pull/29230)) +- Add new overlay text icon, and use for image. ([29215](https://github.com/WordPress/gutenberg/pull/29215)) +- docgen: Add TypeScript support. ([29189](https://github.com/WordPress/gutenberg/pull/29189)) +- Template part block: Add variations based on areas. ([29122](https://github.com/WordPress/gutenberg/pull/29122)) +- Components: Add Popover. ([29084](https://github.com/WordPress/gutenberg/pull/29084)) +- Add Missing URL state to Navigation Link Block. ([28861](https://github.com/WordPress/gutenberg/pull/28861)) +- Improve dropcap behavior. ([28685](https://github.com/WordPress/gutenberg/pull/28685)) +- Improve the block editor handbook table of content. ([28665](https://github.com/WordPress/gutenberg/pull/28665)) +- Site Editor: Persistent List View. ([28637](https://github.com/WordPress/gutenberg/pull/28637)) +- RN: Add Bottom Sheet Select Control component. ([28543](https://github.com/WordPress/gutenberg/pull/28543)) +- Site Editor: Browsing sidebar templates menu restructure. ([28291](https://github.com/WordPress/gutenberg/pull/28291)) +- RichText: Bypass paste filters for internal paste. ([27967](https://github.com/WordPress/gutenberg/pull/27967)) +- Block Directory: Update search results list UI. ([25521](https://github.com/WordPress/gutenberg/pull/25521)) + + + += 10.1.1 = + +### Bug Fixes + +- withNotices: Ensure that the callback props are stable. ([29491](https://github.com/WordPress/gutenberg/pull/29491)) + +### Various + +- withNotices: Memoize the noticeOperations object. ([29582](https://github.com/WordPress/gutenberg/pull/29582)) + + += 10.1.0 = + +### Features +- Use a modal for the reusable blocks creation flow. ([29040](https://github.com/WordPress/gutenberg/pull/29040)) +- Normalize Image's block toolbar. ([29205](https://github.com/WordPress/gutenberg/pull/29205)) +- Add Items Justification to Social Links. ([28980](https://github.com/WordPress/gutenberg/pull/28980)) + +### Enhancements + +- Improve the sorting algorithm while searching parent pages. ([29143](https://github.com/WordPress/gutenberg/pull/29143)) +- Buttons: Add space-between justification controls. ([29160](https://github.com/WordPress/gutenberg/pull/29160)) +- Avoid focusing blocks when inserting them into the canvas. ([28191](https://github.com/WordPress/gutenberg/pull/28191)) +- Create Block: Use register_block_type_from_metadata to register blocks on the server. ([28883](https://github.com/WordPress/gutenberg/pull/28883)) +- Greatly improve dragging performance of the focal point picker. ([28676](https://github.com/WordPress/gutenberg/pull/28676)) +- Improve block search input's accessible name and placeholder. ([28393](https://github.com/WordPress/gutenberg/pull/28393)) + +### New APIs +- Extend updateBlockAttributes to provide for different attribute changes for each block in the clientIds array. ([29099](https://github.com/WordPress/gutenberg/pull/29099)) + +### Bug Fixes + +- Fix Slash Inserter position. ([29288](https://github.com/WordPress/gutenberg/pull/29288)) +- Fix issue with invisible reset template hover state. ([28912](https://github.com/WordPress/gutenberg/pull/28912)) +- InputControl: Fix labelPosition rendering with new ui/flex component. ([29226](https://github.com/WordPress/gutenberg/pull/29226)) +- Button sizing style fix. ([29208](https://github.com/WordPress/gutenberg/pull/29208)) +- Create Block: Fix the background color in esnext template. ([29223](https://github.com/WordPress/gutenberg/pull/29223)) +- Add border-collapse to default block styles in Table block. ([27628](https://github.com/WordPress/gutenberg/pull/27628)) + +- Navigation Block: + - Fix Navigation Links when post type is not Page or Post. ([28892](https://github.com/WordPress/gutenberg/pull/28892)) + - Fix inline style inheritance. ([28868](https://github.com/WordPress/gutenberg/pull/28868)) + - Fix PHP notice shown when rendering a navigation link block. ([28999](https://github.com/WordPress/gutenberg/pull/28999)) + +- Fix is-hovered event listener. ([28715](https://github.com/WordPress/gutenberg/pull/28715)) +- Fix function call in justify toolbar. ([28955](https://github.com/WordPress/gutenberg/pull/28955)) +- Fix footer icon color. ([29199](https://github.com/WordPress/gutenberg/pull/29199)) +- Show page titles special characters in the parent page selector. ([29104](https://github.com/WordPress/gutenberg/pull/29104)) +- Edit Post: Automatically connect a menu item with the pinnable sidebar plugin. ([29081](https://github.com/WordPress/gutenberg/pull/29081)) +- Make `Modal` component use the aria.labelledby prop. ([29020](https://github.com/WordPress/gutenberg/pull/29020)) +- Fix admin menu scroll on editor page. ([28959](https://github.com/WordPress/gutenberg/pull/28959)) +- Prioritize core blocks in the inserter. ([28945](https://github.com/WordPress/gutenberg/pull/28945)) +- Make the __experimentalCaptureToolbars option work reliably. ([28905](https://github.com/WordPress/gutenberg/pull/28905)) +- Ensure sticky tabs are in front of their panel’s descendants. ([28562](https://github.com/WordPress/gutenberg/pull/28562)) +- Navigation Component: Increase color and padding specificity. ([28619](https://github.com/WordPress/gutenberg/pull/28619)) +- Add note to indicate why priority queue callbacks may be undefined. ([28337](https://github.com/WordPress/gutenberg/pull/28337)) +- Keep initial formatting on paste for Preformatted and Verse components. ([27781](https://github.com/WordPress/gutenberg/pull/27781)) +- Rich text: Keep block ID on split. ([28505](https://github.com/WordPress/gutenberg/pull/28505)) +- Fix cursor on rich text blocks when outline mode is active. ([29106](https://github.com/WordPress/gutenberg/pull/29106)) + + +### Experiments + +- Improve loading method for block styles. ([28358](https://github.com/WordPress/gutenberg/pull/28358)) +- Do not use __experimentalSelector to check the panel title. ([29264](https://github.com/WordPress/gutenberg/pull/29264)) +- Update documentation for social links & theme.json. ([29294](https://github.com/WordPress/gutenberg/pull/29294)) +- Navigation Screen: + - Add block deselection when clicking canvas background. ([28876](https://github.com/WordPress/gutenberg/pull/28876)) + - Improve experience for user creating their first menu. ([28767](https://github.com/WordPress/gutenberg/pull/28767)) + - Fix positioning of nested submenus. ([28934](https://github.com/WordPress/gutenberg/pull/28934)) +- Full Site Editing: + - Use a modal for the template part creation flow. ([29108](https://github.com/WordPress/gutenberg/pull/29108)) + - Add an 'area' term for Template Parts. ([28410](https://github.com/WordPress/gutenberg/pull/28410)) + - Add content menu items preview in Navigation. ([29225](https://github.com/WordPress/gutenberg/pull/29225)) + - Replace locate_template method. ([28942](https://github.com/WordPress/gutenberg/pull/28942)) + - Site Editor: + - Inject theme attribute into template parts too. ([29080](https://github.com/WordPress/gutenberg/pull/29080)) + - Organise semantic template parts. ([29030](https://github.com/WordPress/gutenberg/pull/29030)) + - Show contextual icon in the Inspector's template tab. ([29195](https://github.com/WordPress/gutenberg/pull/29195)) + - Add template tab to sidebar. ([28633](https://github.com/WordPress/gutenberg/pull/28633)) +- Global Styles: + - Support skipping serialization in the color hook (block supports mechanism). ([29142](https://github.com/WordPress/gutenberg/pull/29142)) + - Fix invalid font-family list. ([28960](https://github.com/WordPress/gutenberg/pull/28960)) +- Widgets: + - Use textarea for editing block widgets. ([24899](https://github.com/WordPress/gutenberg/pull/24899)) + - Set container classname dynamically depending on Widget block. ([26375](https://github.com/WordPress/gutenberg/pull/26375)) + - Add Widgets REST API changes from Core-51460. ([29242](https://github.com/WordPress/gutenberg/pull/29242)) +- UI Components: + - Add Surface Component. ([28596](https://github.com/WordPress/gutenberg/pull/28596)) + - Add Elevation Component. ([28593](https://github.com/WordPress/gutenberg/pull/28593)) + - Add FormGroup + ControlLabel components. ([28568](https://github.com/WordPress/gutenberg/pull/28568)) + - Add spinner. ([29146](https://github.com/WordPress/gutenberg/pull/29146)) + - Rename ui files to match simpler scheme. ([28948](https://github.com/WordPress/gutenberg/pull/28948)) + - Add hooks based Scrollable component wrapper. ([28979](https://github.com/WordPress/gutenberg/pull/28979)) + - Add createComponent unit tests. ([28949](https://github.com/WordPress/gutenberg/pull/28949)) + - Add hooks based VisuallyHidden. ([28887](https://github.com/WordPress/gutenberg/pull/28887)) + - Add ControlGroup. ([28982](https://github.com/WordPress/gutenberg/pull/28982)) + - Add Portal. ([28981](https://github.com/WordPress/gutenberg/pull/28981)) + - Update documentation (README + inline docs). ([29128](https://github.com/WordPress/gutenberg/pull/29128)) + - Update color-picker snapshot tests to use diff matching. ([28925](https://github.com/WordPress/gutenberg/pull/28925)) +- Bugs: + - Fix Site Logo Styles. ([29227](https://github.com/WordPress/gutenberg/pull/29227)) + - Template Part: Fallback to missing state if slug or theme is invalid. ([29041](https://github.com/WordPress/gutenberg/pull/29041)) + - Site Editor: + - Fix misalignment with navigation toggle and header. ([29093](https://github.com/WordPress/gutenberg/pull/29093)) + - Fix navigation editor block selection clearing. ([29293](https://github.com/WordPress/gutenberg/pull/29293)) + - Fix navigate to link error. ([29239](https://github.com/WordPress/gutenberg/pull/29239)) + - Fix position and style of "Dashboard" link. ([29034](https://github.com/WordPress/gutenberg/pull/29034)) + - Fix end-to-end test errors introduced by template sidebar. ([28950](https://github.com/WordPress/gutenberg/pull/28950)) + - Widgets: + - Fix widgets preview URL typo. ([29062](https://github.com/WordPress/gutenberg/pull/29062)) + - Fix php error in the widget screen. ([29137](https://github.com/WordPress/gutenberg/pull/29137)) + - Fix legacy widgets not previewing and widgets saving issue. ([29111](https://github.com/WordPress/gutenberg/pull/29111)) + - Fix server rendered widget not previewing. ([29197](https://github.com/WordPress/gutenberg/pull/29197)) + + +### Documentation + +- Add accessibility testing instructions. ([28947](https://github.com/WordPress/gutenberg/pull/28947)) +- Updates to Outreach Page. ([28929](https://github.com/WordPress/gutenberg/pull/28929)) +- Update Create a Block tutorial to use `block.json`. ([29027](https://github.com/WordPress/gutenberg/pull/29027)) +- Expose Block Directory references in the handbook. ([29025](https://github.com/WordPress/gutenberg/pull/29025)) +- Update "key concepts". ([28973](https://github.com/WordPress/gutenberg/pull/28973)) +- Remove Font style, weight, decoration, and transform presets from the theme.json documentation. ([29200](https://github.com/WordPress/gutenberg/pull/29200)) +- Combobox Control: Update API doc. ([28787](https://github.com/WordPress/gutenberg/pull/28787)) +- Add block variations to FAQ. ([29154](https://github.com/WordPress/gutenberg/pull/29154), [29170](https://github.com/WordPress/gutenberg/pull/29170)) +- Add templates and global styles to key concepts. ([29071](https://github.com/WordPress/gutenberg/pull/29071)) +- Update block metadata section to promote PHP API. ([29023](https://github.com/WordPress/gutenberg/pull/29023)) +- Fix the header links, add link to user documentation. ([28857](https://github.com/WordPress/gutenberg/pull/28857)) + +### Code Quality +- Replace store name literals in `block-library`. ([28975](https://github.com/WordPress/gutenberg/pull/28975)) +- Fix typos in PHP comments. ([29198](https://github.com/WordPress/gutenberg/pull/29198)) + +- Format TS files according to coding styles. ([29064](https://github.com/WordPress/gutenberg/pull/29064)) +- WP_Theme_JSON_Resolver: Update translate terminology. ([28944](https://github.com/WordPress/gutenberg/pull/28944)) +- Improve code readability by not passing variables by reference. ([28943](https://github.com/WordPress/gutenberg/pull/28943)) +- Convert navigation link to use hooks and context. ([28996](https://github.com/WordPress/gutenberg/pull/28996)) +- Block props: Avoid memo (block mode). ([29139](https://github.com/WordPress/gutenberg/pull/29139)) + +- Reduce memoized context: + - Block props. ([29183](https://github.com/WordPress/gutenberg/pull/29183)) + - Block nodes. ([29163](https://github.com/WordPress/gutenberg/pull/29163)) +- Use ref callback: + - Iframe, selection clearer, typing observer. ([29114](https://github.com/WordPress/gutenberg/pull/29114)) + - Canvas click redirect & typewriter hooks. ([29105](https://github.com/WordPress/gutenberg/pull/29105)) + - Clipboard handler. ([29090](https://github.com/WordPress/gutenberg/pull/29090)) + - Hover hook. ([29089](https://github.com/WordPress/gutenberg/pull/29089)) + - useBlockProps. ([28917](https://github.com/WordPress/gutenberg/pull/28917)) + - Block nodes. ([29153](https://github.com/WordPress/gutenberg/pull/29153)) + + +### Tools + +- Add support for native TypeScript. ([28879](https://github.com/WordPress/gutenberg/pull/28879)) +- Limit the npm version to be 6. ([29204](https://github.com/WordPress/gutenberg/pull/29204)) +- Run CI jobs on wp prefix branches. ([29194](https://github.com/WordPress/gutenberg/pull/29194)) +- Eslint plugin: Add suggestions to "data-no-store-string-literals" rule. ([28974](https://github.com/WordPress/gutenberg/pull/28974)) +- Update codeowners. ([29280](https://github.com/WordPress/gutenberg/pull/29280)) +- Scripts: + - Coerce live reload port to integer. ([29196](https://github.com/WordPress/gutenberg/pull/29196)) + - Add Python 2.0 to other OSS licenses in license checker. ([28968](https://github.com/WordPress/gutenberg/pull/28968)) + + +- Create Block: Fix issue with processing unrelated engines. ([29066](https://github.com/WordPress/gutenberg/pull/29066)) + + +- Fix spacing in new contributor welcome message. ([28958](https://github.com/WordPress/gutenberg/pull/28958)) +- Add react-i18n package with i18n React bindings. ([28465](https://github.com/WordPress/gutenberg/pull/28465)) +- babel-plugin-makepot: Don't transpile the package code. ([28911](https://github.com/WordPress/gutenberg/pull/28911)) +- docgen: + - Don't transpile the package code. ([28910](https://github.com/WordPress/gutenberg/pull/28910)) + - Replace doctrine with comment-parser. ([28615](https://github.com/WordPress/gutenberg/pull/28615)) +- wp-env: + - Use Simple Git instead of NodeGit. ([28848](https://github.com/WordPress/gutenberg/pull/28848)) + - Fix issue where mappings sources were not downloaded. ([28930](https://github.com/WordPress/gutenberg/pull/28930)) +- Changelog script: More fine-grained Changelogs for patch releases. ([28424](https://github.com/WordPress/gutenberg/pull/28424)) +- End 2 End Tests: + - end-to-end Tests: Add gallery caption coverage. ([29127](https://github.com/WordPress/gutenberg/pull/29127)) + - Add basic block preview coverage for inserter. ([29117](https://github.com/WordPress/gutenberg/pull/29117)) + - Make navigation editor end-to-end tests more robust. ([28936](https://github.com/WordPress/gutenberg/pull/28936)) +- Testing: Add snapshot-diff. ([28897](https://github.com/WordPress/gutenberg/pull/28897)) + +### Various + +- Add a custom post type icon. ([29232](https://github.com/WordPress/gutenberg/pull/29232)) +- Update text color icon. ([29212](https://github.com/WordPress/gutenberg/pull/29212)) +- Blocks: Map block type definitions that use PHP naming convention for keys. ([28953](https://github.com/WordPress/gutenberg/pull/28953)) +- Safe access to window/document when in node context: + - FocalPointPickerGrid. ([29070](https://github.com/WordPress/gutenberg/pull/29070)) + - Keycodes. ([29069](https://github.com/WordPress/gutenberg/pull/29069)) + - dom-ready. ([29068](https://github.com/WordPress/gutenberg/pull/29068)) + - ResizableBox utils. ([29067](https://github.com/WordPress/gutenberg/pull/29067)) + - ScrollLock. ([29038](https://github.com/WordPress/gutenberg/pull/29038)) + + + += 10.0.2 = + +### Bug Fixes + +- Fix white screen on RTL languages. ([29256](https://github.com/WordPress/gutenberg/pull/29256)) +- Fix Button block borders for the solid style variation. + + += 10.0.1 = + +### Bug Fixes + + - CSS-in-JS: Fix inline comment for select-dropdown (external module) + + += 10.0.0 = + +### Features + +- Add basic pages block. ([28265](https://github.com/WordPress/gutenberg/pull/28265)) + +### Enhancements + +- Make the parent block selector visible and offset in the block toolbar. ([28598](https://github.com/WordPress/gutenberg/pull/28598)) ([28721](https://github.com/WordPress/gutenberg/pull/28721)) +- Update the social empty state for dark themes. ([28838](https://github.com/WordPress/gutenberg/pull/28838)) +- Add the tag name selector to the advanced panel of the Group block. ([28576](https://github.com/WordPress/gutenberg/pull/28576)) +- Categories block: Display message instead of empty content. ([28697](https://github.com/WordPress/gutenberg/pull/28697)) +- Show block patterns in the inserter for non-root level insert position. ([28459](https://github.com/WordPress/gutenberg/pull/28459)) +- A11y: Improve the keyboard navigation in the block patterns inserter. ([28520](https://github.com/WordPress/gutenberg/pull/28520)) +- Allow transforming Paragraph blocks to Buttons block. ([28508](https://github.com/WordPress/gutenberg/pull/28508)) +- Better top toolbar arrow gap. ([28832](https://github.com/WordPress/gutenberg/pull/28832)) +- Update layout icon to use the new design language. ([28651](https://github.com/WordPress/gutenberg/pull/28651)) +- Update the buttons icons. ([28583](https://github.com/WordPress/gutenberg/pull/28583)) + +### New APIs + +- @wordpress/data: Graduate the __experimentalResolveSelect function to a stable status. ([28544](https://github.com/WordPress/gutenberg/pull/28544)) +- @wordpress/compose: Add useMergeRef React hook. ([27768](https://github.com/WordPress/gutenberg/pull/27768)) +- Components: Allow extra props for RadioControl component. ([28631](https://github.com/WordPress/gutenberg/pull/28631)) +- Add JustifyToolbar component to `@wordpress/block-editor`. ([28439](https://github.com/WordPress/gutenberg/pull/28439)) +- @wordpress/i18n: Add new APIs for React bindings. ([28784](https://github.com/WordPress/gutenberg/pull/28784)) ([28725](https://github.com/WordPress/gutenberg/pull/28725)) + + +### Bug Fixes + +- Fix block insertion a11y string. ([28871](https://github.com/WordPress/gutenberg/pull/28871)) +- Fix npm 7 compatability. ([28824](https://github.com/WordPress/gutenberg/pull/28824)) +- RangeControl: Fix input / slider widths. ([28816](https://github.com/WordPress/gutenberg/pull/28816)) +- Fix post title icon color. ([28727](https://github.com/WordPress/gutenberg/pull/28727)) +- Fix most used blocks usage persistence. ([28694](https://github.com/WordPress/gutenberg/pull/28694)) +- Use consistent icon width for the block icon in the block inspector. ([28666](https://github.com/WordPress/gutenberg/pull/28666)) +- Fix for Latest Posts focus not selectable. ([28660](https://github.com/WordPress/gutenberg/pull/28660)) +- Fix issue where gallery block requests all attachments when empty. ([28621](https://github.com/WordPress/gutenberg/pull/28621)) +- Fix handling of custom unit theme setting. ([28603](https://github.com/WordPress/gutenberg/pull/28603)) +- Fix wrong space-between style in the Buttons block. ([28485](https://github.com/WordPress/gutenberg/pull/28485)) +- Calculate insertion usage for block variations properly. ([28663](https://github.com/WordPress/gutenberg/pull/28663)) +- Fix the default Buttons block radius, and size. ([28514](https://github.com/WordPress/gutenberg/pull/28514)) +- Fix the Cover block height. ([28455](https://github.com/WordPress/gutenberg/pull/28455)) + +### Experiments + +- Site Editor: + - Fix empty content when creating a new template. ([28882](https://github.com/WordPress/gutenberg/pull/28882)) + - Fix complementary area not opening. ([28732](https://github.com/WordPress/gutenberg/pull/28732)) + - Fix inserter can't be closed. ([28590](https://github.com/WordPress/gutenberg/pull/28590)) + - Fix gray screen on refresh when editing pages and posts. ([28413](https://github.com/WordPress/gutenberg/pull/28413)) + - Show single post template in posts templates in the navigation sidebar. ([28229](https://github.com/WordPress/gutenberg/pull/28229)) + - Allow searching pages, posts and categories in the navigation sidebar. ([27280](https://github.com/WordPress/gutenberg/pull/27280)) +- Full Site Editing Architecture: + - Iterate on the public API of WP_Theme_JSON_Resolver. ([28855](https://github.com/WordPress/gutenberg/pull/28855)) + - Rename pageTemplates configuration to customTemplates in theme.json. ([28830](https://github.com/WordPress/gutenberg/pull/28830)) + - Move theme.json support check to class. ([28788](https://github.com/WordPress/gutenberg/pull/28788)) + - Improve performance on file access of `experimental-theme.json`. ([28786](https://github.com/WordPress/gutenberg/pull/28786)) + - Load page templates via theme.json abstractions. ([28700](https://github.com/WordPress/gutenberg/pull/28700)) +- Full Site Editing blocks: + - Post Featured Image block: Render nothing if featured image doesn't exist. ([28625](https://github.com/WordPress/gutenberg/pull/28625)) + - Add a description to the template part block. ([28839](https://github.com/WordPress/gutenberg/pull/28839)) + - Move template part title field to the block inspector. ([28835](https://github.com/WordPress/gutenberg/pull/28835)) + - Use display title for template part block type toolbar anchor. ([28691](https://github.com/WordPress/gutenberg/pull/28691)) + - Allow the query block to work on singular pages when inheriting the global query. ([28351](https://github.com/WordPress/gutenberg/pull/28351)) + - Query Pagination block: cleanup. ([28831](https://github.com/WordPress/gutenberg/pull/28831)) + - Enqueue comment-reply script when post-comments-form block gets rendered. ([28826](https://github.com/WordPress/gutenberg/pull/28826)) +- Navigation Block: + - Fix transparent navigation block submenus. ([28904](https://github.com/WordPress/gutenberg/pull/28904)) + - Polish social links when inside navigation. ([28836](https://github.com/WordPress/gutenberg/pull/28836)), ([28448](https://github.com/WordPress/gutenberg/pull/28448)). + - Add block variation matcher to display information from a found match. ([28626](https://github.com/WordPress/gutenberg/pull/28626)) + - Add new Post Navigation Link block. ([28602](https://github.com/WordPress/gutenberg/pull/28602)) +- Navigation screen: + - Fix failing request for menu items. ([28764](https://github.com/WordPress/gutenberg/pull/28764)) + - Design Iteration. ([28675](https://github.com/WordPress/gutenberg/pull/28675)) + - Clear block selection in the navigation editor when clicking editor canvas. ([28382](https://github.com/WordPress/gutenberg/pull/28382)) +- Block-based widgets screen and customizer: + - Add experimental flag and enable widgets screen in customizer. ([28618](https://github.com/WordPress/gutenberg/pull/28618)) +- Global Styles: + - Use context when translating entries in theme.json. ([28246](https://github.com/WordPress/gutenberg/pull/28246)) +- REST API: + - Add URL Details endpoint to REST API to allow retrieval of info about a remote URL. ([18042](https://github.com/WordPress/gutenberg/pull/18042)) + - Pattern Directory API: Return the block pattern value as content. ([28799](https://github.com/WordPress/gutenberg/pull/28799)) + - Pattern Directory API: Add a `keyword` filter parameter. ([28794](https://github.com/WordPress/gutenberg/pull/28794)) +- UI Components: + - Group all experimental components in the `ui` folder. ([28624](https://github.com/WordPress/gutenberg/pull/28624)) + - Fix types. ([28571](https://github.com/WordPress/gutenberg/pull/28571)) + - Add VStack component. ([28798](https://github.com/WordPress/gutenberg/pull/28798)) + - Add HStack component. ([28707](https://github.com/WordPress/gutenberg/pull/28707)) + - Add Flex component. ([28609](https://github.com/WordPress/gutenberg/pull/28609)) + +### Documentation + +- Theme.json Documentation: Clarify naming schema for CSS Custom Properties. ([28639](https://github.com/WordPress/gutenberg/pull/28639)) +- Update Versions in WordPress to include 5.6.1 & 5.7. ([28641](https://github.com/WordPress/gutenberg/pull/28641)) +- Typos and tweaks: ([28667](https://github.com/WordPress/gutenberg/pull/28667)), ([28657](https://github.com/WordPress/gutenberg/pull/28657)), ([28655](https://github.com/WordPress/gutenberg/pull/28655)), ([28898](https://github.com/WordPress/gutenberg/pull/28898)), ([28894](https://github.com/WordPress/gutenberg/pull/28894)), ([28762](https://github.com/WordPress/gutenberg/pull/28762)), ([28877](https://github.com/WordPress/gutenberg/pull/28877)). + +### Code Quality + +- Improve ButtonBlockAppender styles. ([28464](https://github.com/WordPress/gutenberg/pull/28464)) +- Blocks: Move the logic for Template Part label to the block. ([28828](https://github.com/WordPress/gutenberg/pull/28828)) +- @wordpress/block-directory package: Replace string store names. ([28777](https://github.com/WordPress/gutenberg/pull/28777)) +- @wordpress/block-editor package: Replace string store names. ([28775](https://github.com/WordPress/gutenberg/pull/28775)) +- Site Editor: Replace core/edit-site store name with store object. ([28722](https://github.com/WordPress/gutenberg/pull/28722)), ([28695](https://github.com/WordPress/gutenberg/pull/28695)) +- Relax JSDoc validation for typed packages. ([28729](https://github.com/WordPress/gutenberg/pull/28729)) +- Change apt command to apt-get command. ([28840](https://github.com/WordPress/gutenberg/pull/28840)) +- Refactor Buttons block to use JustifyToolbar controls. ([28768](https://github.com/WordPress/gutenberg/pull/28768)) +- i18n hooks: Don't use typeof to check value falsiness. ([28733](https://github.com/WordPress/gutenberg/pull/28733)) +- Components: Set a default for the ComboboxControl onFilterValueChange. ([28492](https://github.com/WordPress/gutenberg/pull/28492)) + +### Tools + +- List all dependencies when checking licenses in NPM 7. ([28909](https://github.com/WordPress/gutenberg/pull/28909)) +- Allow blank GitHub issues again. ([28866](https://github.com/WordPress/gutenberg/pull/28866)) +- wp-env.json: Pin tt1-blocks dependency to v0.4.3. ([28741](https://github.com/WordPress/gutenberg/pull/28741)) +- Add eslint rule for preventing string literals in select/dispatch/useDispatch. ([28726](https://github.com/WordPress/gutenberg/pull/28726)) +- build-worker: Extract the functions that build CSS and JS. ([28724](https://github.com/WordPress/gutenberg/pull/28724)) +- Unit Tests Workflow: Enable for documentation-only PRs. ([28696](https://github.com/WordPress/gutenberg/pull/28696)) +- Fix end-to-end failures on 'Front Page' template. ([28638](https://github.com/WordPress/gutenberg/pull/28638)) +- Fix lint issues (proper number of spaces). ([28629](https://github.com/WordPress/gutenberg/pull/28629)) +- Fix legacy settings tests for custom spacing. ([28628](https://github.com/WordPress/gutenberg/pull/28628)) +- end-to-end tests: Handle upgrade screen. ([28592](https://github.com/WordPress/gutenberg/pull/28592)) +- Add eslint rules to guard against unexpected imports/exports. ([28513](https://github.com/WordPress/gutenberg/pull/28513)) +- Add a welcome comment to first time contributor PRs. ([28118](https://github.com/WordPress/gutenberg/pull/28118)) +- end-to-end Tests: Document Settings. ([27715](https://github.com/WordPress/gutenberg/pull/27715)) +- Updating composer packages for php8 compatibility. ([28623](https://github.com/WordPress/gutenberg/pull/28623)) + +### Various + +- Adjust defaults for COMPONENT_SYSTEM_PHASE variable. ([28772](https://github.com/WordPress/gutenberg/pull/28772)) +- build-worker: Call callback with error when no task for extension. ([28723](https://github.com/WordPress/gutenberg/pull/28723)) + += 9.9.3 = + +### Bug fixes + +- Gallery Block: Add z-index to fig caption to make sure it is still selectable ([28992](https://github.com/WordPress/gutenberg/pull/28992) +- Inserter: Prevent focused block from stealing focus when inserting a new block ([28962](https://github.com/WordPress/gutenberg/pull/28962)) + + += 9.9.2 = + +### Bug fixes + +- Remove duplication of editor styles ([28837](https://github.com/WordPress/gutenberg/pull/28837)) +- Add useMergeRefs hook ([27768](https://github.com/WordPress/gutenberg/pull/27768)) (dependency of 28837) +- Cover: add missing align attr to deprecation ([28796](https://github.com/WordPress/gutenberg/pull/28796)) + += 9.9.1 = + +### Bug fixes + +- Global Styles: enqueue preset classes in the front-end. +- Global Styles: load styles in iframed site editor. + + += 9.9.0 = + +### Enhancements + +- Try more muted sibling inserter. ([28550](https://github.com/WordPress/gutenberg/pull/28550)) +- Make sure toggleProps doesn't replace important props on ToolbarGroup. ([28401](https://github.com/WordPress/gutenberg/pull/28401)) +- Improve visual clarity of reusable block. ([28318](https://github.com/WordPress/gutenberg/pull/28318)) +- Dark Theme Support: Allow for theme modifications. ([28233](https://github.com/WordPress/gutenberg/pull/28233)) +- Add disabled support in ToggleControl and FormToggle. ([28228](https://github.com/WordPress/gutenberg/pull/28228)) +- Show the spacer block background on hover. ([28129](https://github.com/WordPress/gutenberg/pull/28129)) +- Social Icons: Add icon & background color options. ([28084](https://github.com/WordPress/gutenberg/pull/28084)) +- Support both horizontal and vertical in-between inserters. ([27860](https://github.com/WordPress/gutenberg/pull/27860)) +- Image Block: Add border radius support. ([27667](https://github.com/WordPress/gutenberg/pull/27667)) +- Overlay on disabled elements, to catch events and show tooltips. ([27529](https://github.com/WordPress/gutenberg/pull/27529)) +- Try: System font for vanilla editor styles. ([26822](https://github.com/WordPress/gutenberg/pull/26822)) +- Only consider legal block types for the block list when transforming files to blocks. ([26816](https://github.com/WordPress/gutenberg/pull/26816)) + +### New APIs + +- Block API: Allow overriding the category for block variations. ([28482](https://github.com/WordPress/gutenberg/pull/28482)) +- Create Block: Add optional support for wp-env. ([28234](https://github.com/WordPress/gutenberg/pull/28234)) +- Make i18n functions filter their return values. ([27966](https://github.com/WordPress/gutenberg/pull/27966)) + +### Breaking Change + +The [format](https://developer.wordpress.org/block-editor/developers/themes/theme-json/) of the `experimental-theme.json` has been updated as per + +- Split global block selector into root and defaults. ([28533](https://github.com/WordPress/gutenberg/pull/28533)) +- Make settings and style top-level keys. ([28110](https://github.com/WordPress/gutenberg/pull/28110)) + +Before: + +```json +{ + "global": { + "settings": { ... }, + "styles": { ... } + }, + "core/paragraph": { + "settings": { ... }, + "styles": { ... } + } +} +``` + +After: + +```json +{ + "settings": { + "defaults": { ... }, + "root": { ... }, + "core/paragraph": { ... } + }, + "styles": { + "root": { ... }, + "core/paragraph": { ... } + } +} +``` + +### Bug Fixes + +- Fix sibling inserter color. ([28579](https://github.com/WordPress/gutenberg/pull/28579)) +- Fix issues causing the cover block to black out with a fixed background. ([28565](https://github.com/WordPress/gutenberg/pull/28565)) +- Fix site editor pins. ([28547](https://github.com/WordPress/gutenberg/pull/28547)) +- Resolve issue where insertion point is in incorrect position after changing block selection. ([28542](https://github.com/WordPress/gutenberg/pull/28542)) +- Components: Fix truncate export. ([28527](https://github.com/WordPress/gutenberg/pull/28527)) +- Pinned items regression followup. ([28526](https://github.com/WordPress/gutenberg/pull/28526)) +- Fix regression with pinned plugin items on mobile. ([28521](https://github.com/WordPress/gutenberg/pull/28521)) +- Fix margins and width of 100%-width buttons. ([28467](https://github.com/WordPress/gutenberg/pull/28467)) +- Fix regression caused by #28395. ([28462](https://github.com/WordPress/gutenberg/pull/28462)) +- Fix aborted rendering of non-nested reusable blocks. ([28461](https://github.com/WordPress/gutenberg/pull/28461)) +- Show insertion point after the last block in a container. ([28418](https://github.com/WordPress/gutenberg/pull/28418)) +- Reusable blocks: Prevent infinite recursion. ([28405](https://github.com/WordPress/gutenberg/pull/28405)) +- Fix block inserter automatic reorder. ([28392](https://github.com/WordPress/gutenberg/pull/28392)) +- Create Block: Extract the package name from the template value. ([28383](https://github.com/WordPress/gutenberg/pull/28383)) +- Fix handling of raw transforms that return multiple blocks. ([28371](https://github.com/WordPress/gutenberg/pull/28371)) +- Fix repeated backgrounds with transparent images. ([28362](https://github.com/WordPress/gutenberg/pull/28362)) +- Ensure inline image width popover doesn't appear over media library modal. ([28333](https://github.com/WordPress/gutenberg/pull/28333)) +- Fix bad var name in BlockParentSelector. ([28325](https://github.com/WordPress/gutenberg/pull/28325)) +- Fix repeated backgrounds for cover srcset. ([28310](https://github.com/WordPress/gutenberg/pull/28310)) +- Simple wording fix. ([28288](https://github.com/WordPress/gutenberg/pull/28288)) +- Fix allowedFormats in RichText component. ([28282](https://github.com/WordPress/gutenberg/pull/28282)) +- Fix file formatting for end-to-end test plugin. ([28266](https://github.com/WordPress/gutenberg/pull/28266)) +- Fix backwards compatibility issue with Inline Image format. ([28223](https://github.com/WordPress/gutenberg/pull/28223)) +- Inserter: Fix left padding on Block Pattern Inserter dropdown. ([28150](https://github.com/WordPress/gutenberg/pull/28150)) +- Fix toolbar keyboard navigation after pressing alt+F10. ([28068](https://github.com/WordPress/gutenberg/pull/28068)) +- Image Block: Update linkDestination when editing image link URL. ([27801](https://github.com/WordPress/gutenberg/pull/27801)) +- Fix for: [Interface Skeleton] Limit the editor width to prevent some blocks to grow infinitely wide. ([27695](https://github.com/WordPress/gutenberg/pull/27695)) +- Button component: Add margin around the dash icon. ([27461](https://github.com/WordPress/gutenberg/pull/27461)) +- Fix issue where resetBlocks can result in an incorrect block selection. ([21598](https://github.com/WordPress/gutenberg/pull/21598)) +- Fix Cover block position. ([28653](https://github.com/WordPress/gutenberg/pull/28653)) +- Add minHeightUnit to latest core/cover deprecation. ([28627](https://github.com/WordPress/gutenberg/pull/28627)) + +### Experiments + +- Try: Fix menu item word wrap. ([28516](https://github.com/WordPress/gutenberg/pull/28516)) +- Fix URL cutoff. ([28515](https://github.com/WordPress/gutenberg/pull/28515)) +- Mark Post Comments Warning as block. ([28511](https://github.com/WordPress/gutenberg/pull/28511)) +- Add widget id to blocks in the widgets screen. ([28379](https://github.com/WordPress/gutenberg/pull/28379)) +- Remove new navigation block features in the navigation editor. ([28378](https://github.com/WordPress/gutenberg/pull/28378)) +- Full Site Editing: Update theme attribute injection and removal. ([28368](https://github.com/WordPress/gutenberg/pull/28368)) +- Template Part - fix labels shown - use title instead of slug. ([28330](https://github.com/WordPress/gutenberg/pull/28330)) +- Root element & border radius. ([28320](https://github.com/WordPress/gutenberg/pull/28320)) +- FSE: Parse the template before gets rendered. ([28319](https://github.com/WordPress/gutenberg/pull/28319)) +- Site Editor: Use correct title property in snackbar after inserting Template Part. ([28306](https://github.com/WordPress/gutenberg/pull/28306)) +- Edit Site: Fix templates export. ([28292](https://github.com/WordPress/gutenberg/pull/28292)) +- Hide query block toolbar settings if query is inherited. ([28290](https://github.com/WordPress/gutenberg/pull/28290)) +- Site Editor: Add template part missing state. ([28277](https://github.com/WordPress/gutenberg/pull/28277)) +- Site Editor: Hide resize handle. ([28272](https://github.com/WordPress/gutenberg/pull/28272)) +- Fix save, undo and redo keyboard shortcuts in navigation editor. ([28257](https://github.com/WordPress/gutenberg/pull/28257)) +- Fix template part border states. ([28241](https://github.com/WordPress/gutenberg/pull/28241)) +- Fix entity spotlight system. ([28239](https://github.com/WordPress/gutenberg/pull/28239)) +- Fix the nav menu justify controls menu style. ([28222](https://github.com/WordPress/gutenberg/pull/28222)) +- Polish the appender focus style. ([28219](https://github.com/WordPress/gutenberg/pull/28219)) +- Core Data: Add __experimentalBatch(). ([28210](https://github.com/WordPress/gutenberg/pull/28210)) +- Post Title block: Add placeholder state. ([28198](https://github.com/WordPress/gutenberg/pull/28198)) +- Fix navigation editor error. ([28190](https://github.com/WordPress/gutenberg/pull/28190)) +- Try: Allow space between on menu items. ([28169](https://github.com/WordPress/gutenberg/pull/28169)) +- Query pagination with InnerBlocks. ([28125](https://github.com/WordPress/gutenberg/pull/28125)) +- Template Parts: Fix loading issue. ([28088](https://github.com/WordPress/gutenberg/pull/28088)) +- Add support for border configuration via theme.json. ([28049](https://github.com/WordPress/gutenberg/pull/28049)) +- [Widgets screen] Fix categorization not showing in the global inserter. ([28036](https://github.com/WordPress/gutenberg/pull/28036)) +- Update the layout of the title in the top bar while template editing. ([27845](https://github.com/WordPress/gutenberg/pull/27845)) +- Expose group/ungroup buttons in site editor. ([27611](https://github.com/WordPress/gutenberg/pull/27611)) +- Disable alignment for innerBlocks of Nav Block. ([27365](https://github.com/WordPress/gutenberg/pull/27365)) +- Add thunk actions to replace rungen and controls. ([27276](https://github.com/WordPress/gutenberg/pull/27276)) +- Navigation Block: Placeholder empty state. ([26947](https://github.com/WordPress/gutenberg/pull/26947)) +- Open dropdown before focus on submenu item. ([25322](https://github.com/WordPress/gutenberg/pull/25322)) + +### Documentation + +- Docs: Add new page for i18n filters. ([28553](https://github.com/WordPress/gutenberg/pull/28553)) +- Docs: Update list of core block categories. ([28483](https://github.com/WordPress/gutenberg/pull/28483)) +- Fixed gramatical error. ([28452](https://github.com/WordPress/gutenberg/pull/28452)) +- Update the main readme with the current Gutenberg project phase. ([28359](https://github.com/WordPress/gutenberg/pull/28359)) +- Docs: Update links used in the developer portal. ([28354](https://github.com/WordPress/gutenberg/pull/28354)) +- Docs: Update links to reference HEAD instead of a specific branch. ([28331](https://github.com/WordPress/gutenberg/pull/28331)) +- Docs: Fix supports color gradient(s). ([28328](https://github.com/WordPress/gutenberg/pull/28328)) +- Chore: Add changelog for 28231. ([28232](https://github.com/WordPress/gutenberg/pull/28232)) +- Block Card: Update readme. ([28226](https://github.com/WordPress/gutenberg/pull/28226)) +- Improve the intro page of the Block Editor Handbook. ([28142](https://github.com/WordPress/gutenberg/pull/28142)) +- Update documentation to use allowedFormats instead of the deprecated formattingControls. ([25639](https://github.com/WordPress/gutenberg/pull/25639)) + +### Code Quality + +- Try: Polish block menu and show only fills when available. ([28486](https://github.com/WordPress/gutenberg/pull/28486)) +- Rename some template part icons. ([28458](https://github.com/WordPress/gutenberg/pull/28458)) +- Block Editor: Add hook: UseNoRecursiveRenders. ([28428](https://github.com/WordPress/gutenberg/pull/28428)) +- Coding Standards: Fix PHPCS warnings. ([28343](https://github.com/WordPress/gutenberg/pull/28343)) +- Change the way RTL styles get enqueued. ([28274](https://github.com/WordPress/gutenberg/pull/28274)) +- Remove code no longer necessary. ([28188](https://github.com/WordPress/gutenberg/pull/28188)) +- Update/simplify case transforms. ([28171](https://github.com/WordPress/gutenberg/pull/28171)) +- Fix non static method WP_Block_Parser::Freeform called statically. ([28017](https://github.com/WordPress/gutenberg/pull/28017)) +- Refactor out CSS gradient from custom-gradient-bar. ([27936](https://github.com/WordPress/gutenberg/pull/27936)) + +### Tools + +- Dependencies: Upgrade TypeScript. ([28586](https://github.com/WordPress/gutenberg/pull/28586)) +- ESLint Plugin: Add missing eslint-plugin-import dependency. ([28545](https://github.com/WordPress/gutenberg/pull/28545)) +- Wp-env: Add MySQL port info to start logs. ([28441](https://github.com/WordPress/gutenberg/pull/28441)) +- Run the load time indicator computation multiple times. ([28419](https://github.com/WordPress/gutenberg/pull/28419)) +- Don't add default-custom-properties styles to all compiled files. ([28395](https://github.com/WordPress/gutenberg/pull/28395)) +- Fix typewriter test by using mouse.wheel and waiting for scroll. ([28376](https://github.com/WordPress/gutenberg/pull/28376)) +- Fix end-to-end tests in widgets screen. ([28375](https://github.com/WordPress/gutenberg/pull/28375)) +- Replace deprecated waitFor in end-to-end tests. ([28360](https://github.com/WordPress/gutenberg/pull/28360)) +- Improve robustness of nav screen test. ([28344](https://github.com/WordPress/gutenberg/pull/28344)) +- Preferences modal redesign. ([28329](https://github.com/WordPress/gutenberg/pull/28329)) +- Site Editor: Add end-to-end tests for templates export. ([28324](https://github.com/WordPress/gutenberg/pull/28324)) +- Site Editor: Add unit test for site templates export. ([28323](https://github.com/WordPress/gutenberg/pull/28323)) +- Fix widgets screen end-to-end tests. ([28264](https://github.com/WordPress/gutenberg/pull/28264)) +- Add more tests for processing theme.json logic. ([28202](https://github.com/WordPress/gutenberg/pull/28202)) +- Update nosolosw notifs. ([28189](https://github.com/WordPress/gutenberg/pull/28189)) +- Remove @talldan from some codeowners paths. ([28182](https://github.com/WordPress/gutenberg/pull/28182)) +- Add stale issue workflow for issues with need info requested. ([28179](https://github.com/WordPress/gutenberg/pull/28179)) +- Custom script distclean to remove node_modules of all packages. ([28177](https://github.com/WordPress/gutenberg/pull/28177)) +- Add some basic end-to-end tests for the widgets screen. ([28160](https://github.com/WordPress/gutenberg/pull/28160)) +- Testing: Add CI workflow covering Node.js 12. ([28139](https://github.com/WordPress/gutenberg/pull/28139)) +- wp-env: Fix upload directory conflict in phpunit service. ([28120](https://github.com/WordPress/gutenberg/pull/28120)) +- Update issue templates. ([27570](https://github.com/WordPress/gutenberg/pull/27570)) + +### Various + +- Make custom spacing work with core. ([28548](https://github.com/WordPress/gutenberg/pull/28548)) +- Component System: Add Grid Component. ([28531](https://github.com/WordPress/gutenberg/pull/28531)) +- Block Validation: Allow unitless zero CSS lengths. ([28501](https://github.com/WordPress/gutenberg/pull/28501)) +- Add check for zero to the FocalPointPicker mediaRef which prevents a division by zero error. ([28499](https://github.com/WordPress/gutenberg/pull/28499)) +- Social Link: Add a class to the anchor element. ([28494](https://github.com/WordPress/gutenberg/pull/28494)) +- Components: Integrate G2 Text component. ([28475](https://github.com/WordPress/gutenberg/pull/28475)) +- Block Mover wording: 'Move block position' to 'Change block position'. ([28454](https://github.com/WordPress/gutenberg/pull/28454)) +- [Documentation] : Fixing grammar. ([28447](https://github.com/WordPress/gutenberg/pull/28447)) +- Docs: Update tree and raw-content links to reference HEAD instead of a specific branch. ([28431](https://github.com/WordPress/gutenberg/pull/28431)) +- Image: Add flow for converting to cover block from toolbar. ([28414](https://github.com/WordPress/gutenberg/pull/28414)) +- Cover: Improve various states. ([28384](https://github.com/WordPress/gutenberg/pull/28384)) +- Update HTML Anchor description to refer to block instead of heading. ([28367](https://github.com/WordPress/gutenberg/pull/28367)) +- Packages: Use canary flag for npm releases with next dist tag. ([28357](https://github.com/WordPress/gutenberg/pull/28357)) +- Packages: Fully automate npm publishing with the latest and next tags. ([28335](https://github.com/WordPress/gutenberg/pull/28335)) +- CODEOWNERS: Tweak for ella. ([28326](https://github.com/WordPress/gutenberg/pull/28326)) +- Block Transform: Fix isMultiBlock property name. ([28321](https://github.com/WordPress/gutenberg/pull/28321)) +- Warning component: Remove extra margin. ([28316](https://github.com/WordPress/gutenberg/pull/28316)) +- Block Directory: Silently avoid re-installing local blocks. ([28304](https://github.com/WordPress/gutenberg/pull/28304)) +- Inserter: Add description to content used in search. ([28301](https://github.com/WordPress/gutenberg/pull/28301)) +- Try: Show reusable block parent border when child selected. ([28283](https://github.com/WordPress/gutenberg/pull/28283)) +- Components: Update dependencies shared with G2 components. ([28280](https://github.com/WordPress/gutenberg/pull/28280)) +- Try: Zero width space in empty paragraph. ([28268](https://github.com/WordPress/gutenberg/pull/28268)) +- Alow setting the crossOrigin attribute for the image transform's image using a filter. ([28255](https://github.com/WordPress/gutenberg/pull/28255)) +- Navigation component: Fix button outline. ([28230](https://github.com/WordPress/gutenberg/pull/28230)) +- Components: Add truncate. ([28176](https://github.com/WordPress/gutenberg/pull/28176)) +- Add panel button props. ([28147](https://github.com/WordPress/gutenberg/pull/28147)) +- Add "Show block breadcrumbs" preference. ([28133](https://github.com/WordPress/gutenberg/pull/28133)) +- NavigationMenu component: Add isSearchDebouncing prop. ([28102](https://github.com/WordPress/gutenberg/pull/28102)) +- Try: Make empty paragraphs take up the same space on the frontend, as in the editor. ([27995](https://github.com/WordPress/gutenberg/pull/27995)) +- Change the block editor inserter quick inserter border color. ([27866](https://github.com/WordPress/gutenberg/pull/27866)) +- Save editors value on change. ([27717](https://github.com/WordPress/gutenberg/pull/27717)) +- Component System: Upgrade FontSizePicker. ([27594](https://github.com/WordPress/gutenberg/pull/27594)) +- Adjust borders on gallery to prevent overlap. ([27312](https://github.com/WordPress/gutenberg/pull/27312)) +- Pattern Directory: Create endpoints to proxy api.w.org/patterns. ([26578](https://github.com/WordPress/gutenberg/pull/26578)) +- Show text labels in block toolbars when option is set. ([26135](https://github.com/WordPress/gutenberg/pull/26135)) +- Block Directory: Filter out disallowed blocks before showing available blocks. ([25926](https://github.com/WordPress/gutenberg/pull/25926)) + += 9.8.4 = + +- Cover Block: + - Fix issues causing the cover block to black out with a fixed background ([28565](https://github.com/WordPress/gutenberg/pull/28565)) + - Fix embed position ([28653](https://github.com/WordPress/gutenberg/pull/28653)) +- Pinned items: + - Fix regression with pinned plugin items on mobile ([28521](https://github.com/WordPress/gutenberg/pull/28521)) + - Pinned items regression followup ([28526](https://github.com/WordPress/gutenberg/pull/28526)) + += 9.8.3 = + +### Bug Fixes + +- Cover Block: Add `minHeightUnit` to latest deprecation. ([28627](https://github.com/WordPress/gutenberg/pull/28627)) + += 9.8.2 = + +### Bug Fixes + +- Cover Block: Prevent division by zero in FocalPointPicker ([28499](https://github.com/WordPress/gutenberg/pull/28499)) +- Block Validation: Allow unitless zero CSS lengths ([28501](https://github.com/WordPress/gutenberg/pull/28501)) + + += 9.8.1 = + +### Bug Fixes + +- Cover Block: + - Revert "Cover: Fix matrix alignment issue. (#28361)" ([28364](https://github.com/WordPress/gutenberg/pull/28364)) + - Fix visual regression. ([28404](https://github.com/WordPress/gutenberg/pull/28404)) +- FSE: fix iframe error in Firefox. ([28212](https://github.com/WordPress/gutenberg/pull/28212)) + + += 9.8.0 = + +### Enhancements + +- Use a semi transparent background for the spacer block when selected. ([28103](https://github.com/WordPress/gutenberg/pull/28103)) +- Display matching variation icon in Block Switcher. ([27903](https://github.com/WordPress/gutenberg/pull/27903)) + +### New APIs + +- Create Block: Allow using locally installed packages with templates. ([28105](https://github.com/WordPress/gutenberg/pull/28105)) +- Create block: Add support for static assets. ([28038](https://github.com/WordPress/gutenberg/pull/28038)) +- Compose: Export useIsomorphicLayoutEffect and use it. ([28023](https://github.com/WordPress/gutenberg/pull/28023)) + +### Bug Fixes + +- Reusable Blocks: + - Show an error message when a reusable block has gone missing. ([28126](https://github.com/WordPress/gutenberg/pull/28126)) + - Fix dismiss notice after error. ([28015](https://github.com/WordPress/gutenberg/pull/28015)) +- Cover Block: + - Fix nested cover block bug. ([28114](https://github.com/WordPress/gutenberg/pull/28114)) + - Fix invalid cover block transforms. ([28087](https://github.com/WordPress/gutenberg/pull/28087)) + - Fix cover regression. ([28287](https://github.com/WordPress/gutenberg/pull/28287)) + - Fix Cover focal point picker. ([28350](https://github.com/WordPress/gutenberg/pull/28350)) + - Fix matrix alignment issue. ([28361](https://github.com/WordPress/gutenberg/pull/28361)) +- Fix block error when transforming blocks with Link Popover opened. ([28136](https://github.com/WordPress/gutenberg/pull/28136)) +- Fix PHP Notice in navigation-link. ([28134](https://github.com/WordPress/gutenberg/pull/28134)) +- Prevent link paste in RichText components in Button and Navigation blocks. ([28130](https://github.com/WordPress/gutenberg/pull/28130)) +- Fix floating date status inferred for posts where the status has been edited. ([28127](https://github.com/WordPress/gutenberg/pull/28127)) +- BlockSwitcher: Fix crash due to null reference. ([28122](https://github.com/WordPress/gutenberg/pull/28122)) +- Verse: Fix line-wrap rendering on front-end of site. ([28109](https://github.com/WordPress/gutenberg/pull/28109)) +- FocalPointPicker: Fix rendering and dragging experience. ([28096](https://github.com/WordPress/gutenberg/pull/28096)) +- Block Directory: Fix "missing" block when the block can be installed from the directory. ([28030](https://github.com/WordPress/gutenberg/pull/28030)) +- Fix locked template not updating when inner blocks template prop changes. ([28007](https://github.com/WordPress/gutenberg/pull/28007)) +- Fix editor crash when registering a block pattern without `categories`. ([27970](https://github.com/WordPress/gutenberg/pull/27970)) +- Fix the RTL editor styles and the theme styles option. ([27947](https://github.com/WordPress/gutenberg/pull/27947)) +- Don't close the block inserter when clicking the scrollbar or an empty area. ([27946](https://github.com/WordPress/gutenberg/pull/27946)) +- Fix AlignmentMatrixControl focus issue. ([27945](https://github.com/WordPress/gutenberg/pull/27945)) +- Fix unexpected autosave for published posts. ([27942](https://github.com/WordPress/gutenberg/pull/27942)) +- Fix RadioGroup to support zero as a Radio value. ([27906](https://github.com/WordPress/gutenberg/pull/27906)) +- Update embed block transforms to permit multiple links to be pasted in a paragraph (#27551). ([27746](https://github.com/WordPress/gutenberg/pull/27746)) +- Change the week header and left button style to meet the date spacing. ([27730](https://github.com/WordPress/gutenberg/pull/27730)) +- Add aria labels to box control component inputs/button. ([27727](https://github.com/WordPress/gutenberg/pull/27727)) +- Use clientWidth when no width is available for cropper. ([27687](https://github.com/WordPress/gutenberg/pull/27687)) +- Core Data: Normalize `_fields` value for use in `stableKey`. ([27526](https://github.com/WordPress/gutenberg/pull/27526)) +- Fix appender margins again. ([27392](https://github.com/WordPress/gutenberg/pull/27392)) + +### Performance + +- Components: Expose composite API from Reakit. ([28085](https://github.com/WordPress/gutenberg/pull/28085)) +- Improve Inserter block hover performance. ([26348](https://github.com/WordPress/gutenberg/pull/26348)) + +### Experiments + +- Full Site Editing Framework: + - Load content in iframe. ([25775](https://github.com/WordPress/gutenberg/pull/25775)) + - Avoid using auto-drafts for theme templates and template parts. ([27910](https://github.com/WordPress/gutenberg/pull/27910)) + - Delete unused options while upgrading the plugin. ([28164](https://github.com/WordPress/gutenberg/pull/28164)) + - Fix _wp_file_based term deletion in migration. ([28300](https://github.com/WordPress/gutenberg/pull/28300)) + - Fix the border radius in the site editor. ([27986](https://github.com/WordPress/gutenberg/pull/27986)) +- theme.json: + - Add border radius to the theme styles schema. ([27791](https://github.com/WordPress/gutenberg/pull/27791)) + - Add theme.json i18n mechanism and JSON file specifying which theme.json paths are translatable. ([27380](https://github.com/WordPress/gutenberg/pull/27380)) + - Add: Save time theme.json escaping. ([28061](https://github.com/WordPress/gutenberg/pull/28061)) +- Group Block: Add border radius. ([27665](https://github.com/WordPress/gutenberg/pull/27665)) +- Hide the theme without comments.php deprecation message. ([28128](https://github.com/WordPress/gutenberg/pull/28128)) +- Fix navigation editor. ([28080](https://github.com/WordPress/gutenberg/pull/28080)) +- Widgets: Temporary fix for saving widgets. ([28078](https://github.com/WordPress/gutenberg/pull/28078)) +- Decouple query from edit site. ([27972](https://github.com/WordPress/gutenberg/pull/27972)) +- Only enable the template mode for viewable post types. ([27948](https://github.com/WordPress/gutenberg/pull/27948)) +- Box control units: Ensure custom units are preserved. ([27800](https://github.com/WordPress/gutenberg/pull/27800)) +- Navigation Block: Use draft status when user creates a post and don't render unpublished posts in menus. ([27207](https://github.com/WordPress/gutenberg/pull/27207)) + +### Documentation + +- Docs: Improve README file for `@wordpress/create-block`. ([28052](https://github.com/WordPress/gutenberg/pull/28052)) +- Create Block: Update the demo included in the README file. ([28037](https://github.com/WordPress/gutenberg/pull/28037)) +- Docs: Switch heading to Quick Start for consistency. ([28019](https://github.com/WordPress/gutenberg/pull/28019)) +- Docs: A wether, as it turns out, is a castrated ram. ([28008](https://github.com/WordPress/gutenberg/pull/28008)) +- Update Quickstart guide for the Development Environment documentation. ([28005](https://github.com/WordPress/gutenberg/pull/28005)) +- Update copyright year to 2021 in `license.md`. ([27951](https://github.com/WordPress/gutenberg/pull/27951)) +- Block API: Add more inline comments. ([20257](https://github.com/WordPress/gutenberg/pull/20257)) +- Changelog: Group entries for 9.8.0-rc.1. ([28332](https://github.com/WordPress/gutenberg/pull/28332)) + +### Code Quality + +- Remove effects test file and remove unused refx dependency. ([28162](https://github.com/WordPress/gutenberg/pull/28162)) +- Annotations: Replace store name string with exposed store definition. ([28156](https://github.com/WordPress/gutenberg/pull/28156)) +- Edit Widgets: Replace store name string with exposed store definition. ([28044](https://github.com/WordPress/gutenberg/pull/28044)) +- Interface: Replace store name string with exposed store definition. ([28041](https://github.com/WordPress/gutenberg/pull/28041)) +- Upgrade Reakit to version 1.3.4. ([28013](https://github.com/WordPress/gutenberg/pull/28013)) +- Fix PHPCS warning: Undefined variable $i. ([27955](https://github.com/WordPress/gutenberg/pull/27955)) +- Consolidate block editor initializations. ([27954](https://github.com/WordPress/gutenberg/pull/27954)) +- Fix create-block PHP template files according to WordPress standards. ([27949](https://github.com/WordPress/gutenberg/pull/27949)) +- block-directory: Simplify the LOAD_ASSETS flow by making it an async function. ([25956](https://github.com/WordPress/gutenberg/pull/25956)) + +### Tools + +- Workflows (i.e. GitHub Actions): + - Create Release Draft when tagging version. ([27488](https://github.com/WordPress/gutenberg/pull/27488)) + - Add action to upload release to SVN repo. ([27591](https://github.com/WordPress/gutenberg/pull/27591)) + - Compare Performance upon Release. ([28046](https://github.com/WordPress/gutenberg/pull/28046)) + - Build Plugin Workflow: Bump node version to 14. ([28048](https://github.com/WordPress/gutenberg/pull/28048)) +- End-to-end tests: + - FSE: Fix intermittent errors in multi entity editing test. ([28107](https://github.com/WordPress/gutenberg/pull/28107)) + - Fix randomly failing end-to-end test. ([28073](https://github.com/WordPress/gutenberg/pull/28073)) + - Upgrade puppeteer to 5.5.0. ([28055](https://github.com/WordPress/gutenberg/pull/28055)) + - Performance tests: Fix. ([28026](https://github.com/WordPress/gutenberg/pull/28026)) +- Scripts: + - Align default engines for `check-engines` with the package. ([28143](https://github.com/WordPress/gutenberg/pull/28143)) + - Add support for static assets in build commands. ([28043](https://github.com/WordPress/gutenberg/pull/28043)) + - Make it possible to transpile `.jsx` files with build command. ([28002](https://github.com/WordPress/gutenberg/pull/28002)) + - ESLint minor version upgrade to 7.17.0. ([27965](https://github.com/WordPress/gutenberg/pull/27965)) + - Upgrade Jest to the new major version (26.x). ([27956](https://github.com/WordPress/gutenberg/pull/27956)) + - Use @wordpress/stylelint-config in @wordpress/scripts. ([27810](https://github.com/WordPress/gutenberg/pull/27810)) +- Linting: + - ESLint Plugin: Enable import rules used in Gutenberg. ([27387](https://github.com/WordPress/gutenberg/pull/27387)) + - Add no-unsafe-wp-apis to recommended configuration. ([27327](https://github.com/WordPress/gutenberg/pull/27327)) + - Remove /wordpress from test/linting ignore paths. ([20270](https://github.com/WordPress/gutenberg/pull/20270)) + - Update changelog for stylelint-config. ([28074](https://github.com/WordPress/gutenberg/pull/28074)) +- Testing: Prevent a direct usage of Reakit. ([28095](https://github.com/WordPress/gutenberg/pull/28095)) +- Update the minimum Node.js version to 12. ([27934](https://github.com/WordPress/gutenberg/pull/27934)) +- wp-env: Ensure the environment is used with the logs command. ([27907](https://github.com/WordPress/gutenberg/pull/27907)) +- Packages: Fully automate npm publishing with the latest and next tags ([28335](https://github.com/WordPress/gutenberg/pull/28335)) +- Upgrade webpack to version 5. ([26382](https://github.com/WordPress/gutenberg/pull/26382)) +- Revert "Upgrade webpack to version 5". ([27974](https://github.com/WordPress/gutenberg/pull/27974)) + +### Various + +- Gutenpride Template: + - New Package to use with the tutorial. ([27881](https://github.com/WordPress/gutenberg/pull/27881)) + - Create Block: Enhancements to Gutenpride tutorial template. ([28215](https://github.com/WordPress/gutenberg/pull/28215)) +- URL: Remove redundant array coercion. ([28072](https://github.com/WordPress/gutenberg/pull/28072)) +- Visual editor: Remove focusable wrapper. ([28058](https://github.com/WordPress/gutenberg/pull/28058)) +- Readme: Increase tested Version up to WP 5.6. ([28050](https://github.com/WordPress/gutenberg/pull/28050)) +- Interface: Remove deprecated prop from InterfaceSkeleton. ([28034](https://github.com/WordPress/gutenberg/pull/28034)) +- List View: Reduce whitespace and always show nested blocks. ([28029](https://github.com/WordPress/gutenberg/pull/28029)) +- Making the sidebar inspector's tabs stick when scrolling. ([28003](https://github.com/WordPress/gutenberg/pull/28003)) +- Chore: Update Lerna dependency. ([27990](https://github.com/WordPress/gutenberg/pull/27990)) +- Try: Make focus width a CSS variable. ([27968](https://github.com/WordPress/gutenberg/pull/27968)) +- Add translation context to all block's titles. ([27933](https://github.com/WordPress/gutenberg/pull/27933)) +- Add primary destructive button style. ([27774](https://github.com/WordPress/gutenberg/pull/27774)) +- Modifies the widgets dashboard link to point to the new widgets editor. ([26880](https://github.com/WordPress/gutenberg/pull/26880)) +- Use standard select element for small number of authors. ([26426](https://github.com/WordPress/gutenberg/pull/26426)) +- Add srcset for cover image. ([25171](https://github.com/WordPress/gutenberg/pull/25171)) + + += 9.7.4 = + +### Bug Fixes + +- Fix isRTL check by loading the ltr string explicitely. + + += 9.7.3 = + +### Bug Fixes + +- Prevent mangle of translation functions to fix RTL locales. + + += 9.7.2 = + +### Bug Fixes + +- Keep the inserter opened when clicking the scrollbar. + +### Various + +- Updated the "tested up to" WordPress version. + + += 9.7.1 = + +### Bug Fixes + + - Fix styling of the verse block. + + += 9.7.0 = + +### Features + +- Support drag and dropping block patterns from the inserter. ([27927](https://github.com/WordPress/gutenberg/pull/27927)) + +### Enhancements + +- Improve the Reusable Blocks UI by relying on multi entity save flow. ([27887](https://github.com/WordPress/gutenberg/pull/27887)) ([27885](https://github.com/WordPress/gutenberg/pull/27885)) +- Show the insertion point indicator below the inbetween inserter. ([27842](https://github.com/WordPress/gutenberg/pull/27842)) +- Add block transforms previews. ([27861](https://github.com/WordPress/gutenberg/pull/27861)) +- URL: RemoveQueryArgs should remove the ? char after removing all args. ([27812](https://github.com/WordPress/gutenberg/pull/27812)) +- Deburr the input of the Post Author and Parent Page controls when filitering results. ([26611](https://github.com/WordPress/gutenberg/pull/26611)) +- Display block icon, description and name by matching block variations. ([27469](https://github.com/WordPress/gutenberg/pull/27469)) +- RSS Block: Add an explicit border-box CSS rule. ([27767](https://github.com/WordPress/gutenberg/pull/27767)) + +### New APIs + +- Create block: Allow to list npm packages to be installed in the template. ([27880](https://github.com/WordPress/gutenberg/pull/27880)) +- @wordpress/url: Add a maxLength argument to filterURLForDisplay. ([27530](https://github.com/WordPress/gutenberg/pull/27530)) +- Add new package `@wordpress/stylelint config`. ([22777](https://github.com/WordPress/gutenberg/pull/22777)) + +### Bug Fixes + +- Show all taxonomies in Tag Cloud block. ([27930](https://github.com/WordPress/gutenberg/pull/27930)) +- HTML Block: Fix editor styles. ([27627](https://github.com/WordPress/gutenberg/pull/27627)) +- Don't ignore extra edits made in the server when saving posts. ([27929](https://github.com/WordPress/gutenberg/pull/27929)) +- Remove the animation of post publish button during autosaving. ([27874](https://github.com/WordPress/gutenberg/pull/27874)) +- Prevent the inserter from closing when switching the pattern category. ([27792](https://github.com/WordPress/gutenberg/pull/27792)) +- LinkControl: Fix horizontal scrollbar within block toolbar. ([27777](https://github.com/WordPress/gutenberg/pull/27777)) +- Create Block: Fix support for external templates. ([27776](https://github.com/WordPress/gutenberg/pull/27776)) ([27784](https://github.com/WordPress/gutenberg/pull/27784)) +- Fix text color dropdown not opening. ([27596](https://github.com/WordPress/gutenberg/pull/27596)) + +### Experiments + +- Full Site Editing Framework: + - Add support for custom templates in FSE themes. ([27778](https://github.com/WordPress/gutenberg/pull/27778)) + - Refactor the edit-site store to clarify the purpose of templateId and templatePartId. ([27839](https://github.com/WordPress/gutenberg/pull/27839)) +- Full Site Editing Blocks: + - Site Logo: Remove duplicate link. ([27924](https://github.com/WordPress/gutenberg/pull/27924)) + - Post excerpt block: Fix incorrect quotes for the class attribute in the wrapper. ([27895](https://github.com/WordPress/gutenberg/pull/27895)) +- Global Styles: + - Add padding control to the Global Styles sidebar. ([27154](https://github.com/WordPress/gutenberg/pull/27154)) +- Navigation block: Fix the text color for links in the navigation block. ([26698](https://github.com/WordPress/gutenberg/pull/26698)) + +### Documentation + +- Improve documentation for withNotices HOC in components package. ([27863](https://github.com/WordPress/gutenberg/pull/27863)) +- Add ContrastChecker component readme. ([25570](https://github.com/WordPress/gutenberg/pull/25570)) +- Remove default style information from the documentation. ([27811](https://github.com/WordPress/gutenberg/pull/27811)) +- Storybook: Fix broken import statements for DateTime component. ([27794](https://github.com/WordPress/gutenberg/pull/27794)) +- Add additional information about lock inheritance. ([27834](https://github.com/WordPress/gutenberg/pull/27834)) +- Typos andd tweaks: ([27909](https://github.com/WordPress/gutenberg/pull/27909)), ([27799](https://github.com/WordPress/gutenberg/pull/27799)) + +### Code Quality + +- Use a consistent way to check isRTL. ([27838](https://github.com/WordPress/gutenberg/pull/27838)) +- Update the minimum required WordPress version to 5.5. ([27807](https://github.com/WordPress/gutenberg/pull/27807)) +- Remove unused redux-optimist dependency. ([27798](https://github.com/WordPress/gutenberg/pull/27798)) +- Storybook: Perform cleanup in the Storybook setup. ([27786](https://github.com/WordPress/gutenberg/pull/27786)) ([27813](https://github.com/WordPress/gutenberg/pull/27813)) +- Raw handling: Remove duplicate code. ([27758](https://github.com/WordPress/gutenberg/pull/27758)) +- Refactor BlockSwitcher as a functional component. ([27674](https://github.com/WordPress/gutenberg/pull/27674)) +- Rich Text: Replace store name string with exposed store definition. ([27820](https://github.com/WordPress/gutenberg/pull/27820)) + +### Tools + +- Remove overrides for JSDoc rules downgraded to warnings. ([27912](https://github.com/WordPress/gutenberg/pull/27912)) ([27879](https://github.com/WordPress/gutenberg/pull/27879)) +- Plugin release tool: Fix svn add/rm commands for release tool. ([27886](https://github.com/WordPress/gutenberg/pull/27886)) +- Add types to the @wordpress/keycodes package. ([19520](https://github.com/WordPress/gutenberg/pull/19520)) +- end to end tests: + - Make end to end tests do not rely on font size picker classes. ([27825](https://github.com/WordPress/gutenberg/pull/27825)) + - Remove expect.assertions count from multi-entity-saving tests. ([27802](https://github.com/WordPress/gutenberg/pull/27802)) ([27818](https://github.com/WordPress/gutenberg/pull/27818)) + - Testing: Remove axe verification executed after every test case. ([26626](https://github.com/WordPress/gutenberg/pull/26626)) + - Improve font size end to end tests to work with input changes on blur. ([27871](https://github.com/WordPress/gutenberg/pull/27871)) + + + += 9.6.2 = + +### Bug Fixes + + - Fix toolbar controls in the widgets screen. + - Fix the slash inserter in the widgets screen. + + += 9.6.1 = + +### Bugfixes + +- Include block's CSS in the release for FSE themes ([27884](https://github.com/WordPress/gutenberg/pull/27884)) + + = 9.6.0 = @@ -2798,7 +3883,7 @@ Fix action GitHub action workflow YAML syntax errors. ([23844](https://github.co - Global styles provider. ([21637](https://github.com/WordPress/gutenberg/pull/21637)) - Update existing templates to use new blocks. ([21857](https://github.com/WordPress/gutenberg/pull/21857)) - Enable pullquote block. ([21930](https://github.com/WordPress/gutenberg/pull/21930)) -- Merge release branch back to master for v1.27.1. ([22234](https://github.com/WordPress/gutenberg/pull/22234)) +- Merge release branch back to trunk for v1.27.1. ([22234](https://github.com/WordPress/gutenberg/pull/22234)) - Wrap button blocks with buttons blocks in page templates. ([21939](https://github.com/WordPress/gutenberg/pull/21939)) - Components: Create a separate .native entry for ToolbarItem. ([22229](https://github.com/WordPress/gutenberg/pull/22229)) @@ -2822,7 +3907,7 @@ Fix action GitHub action workflow YAML syntax errors. ([23844](https://github.co ### New APIs -- A new [Block Context API](https://github.com/WordPress/gutenberg/blob/master/docs/designers-developers/developers/block-api/block-context.md) has been partially implemented, currently limited to block settings and editor APIs. PHP APIs will be implemented in the next plugin releases. ([21467](https://github.com/WordPress/gutenberg/pull/21467), [21868](https://github.com/WordPress/gutenberg/pull/21868), [21921](https://github.com/WordPress/gutenberg/pull/21921)) +- A new [Block Context API](https://github.com/WordPress/gutenberg/blob/HEAD/docs/designers-developers/developers/block-api/block-context.md) has been partially implemented, currently limited to block settings and editor APIs. PHP APIs will be implemented in the next plugin releases. ([21467](https://github.com/WordPress/gutenberg/pull/21467), [21868](https://github.com/WordPress/gutenberg/pull/21868), [21921](https://github.com/WordPress/gutenberg/pull/21921)) - Add new "G2"-styled icons to the Icons package. ([21209](https://github.com/WordPress/gutenberg/pull/21209)) ### Bug Fixes @@ -4955,7 +6040,7 @@ Add knobs to the [ColorIndicator Story](https://github.com/WordPress/gutenberg/p - Fix Travis instability by [waiting for MySQL availability](https://github.com/WordPress/gutenberg/pull/16461) before install the plugin. - Continue the [generic RichText component](https://github.com/WordPress/gutenberg/pull/16309) refactoring. - Remove the [usage of the editor store](https://github.com/WordPress/gutenberg/pull/16184) from the block editor module. -- Update the [MilestoneIt Github action](https://github.com/WordPress/gutenberg/pull/16511) to read the plugin version from master. +- Update the [MilestoneIt Github action](https://github.com/WordPress/gutenberg/pull/16511) to read the plugin version from trunk. - Refactor the post meta block attributes to use a generic [custom sources mechanism](https://github.com/WordPress/gutenberg/pull/16402). - Expose [position prop in DotTip](https://github.com/WordPress/gutenberg/pull/14972) component. - Avoid docker [containers automatic restart](https://github.com/WordPress/gutenberg/pull/16547). @@ -6804,7 +7889,7 @@ Add knobs to the [ColorIndicator Story](https://github.com/WordPress/gutenberg/p * Fix keyboard interaction (up/down arrow keys) causing focus to transfer out of the default block’s insertion menu. * Fix regression causing dynamic blocks not rendering in the frontend. * Fix vertical alignment issue on Media & Text block. -* Fix some linter errors in master branch. +* Fix some linter errors in trunk branch. * Fix dash line in More/Next-Page blocks. * Fix missing Categories block label. * Fix embedding and demo tests. @@ -8939,7 +10024,7 @@ Add knobs to the [ColorIndicator Story](https://github.com/WordPress/gutenberg/p * Add security reporting instructions. * Improve useOnce documentation. * Bump copyright year to 2018 in license.md. -* Disable Travis branch builds except for master. +* Disable Travis branch builds except for trunk. = 2.0.0 = diff --git a/composer.json b/composer.json index 2a16d1accff3e9..3e6346fa821f98 100644 --- a/composer.json +++ b/composer.json @@ -20,7 +20,7 @@ "wp-coding-standards/wpcs": "^2.2", "sirbrillig/phpcs-variable-analysis": "^2.8", "wp-phpunit/wp-phpunit": "^5.4", - "phpunit/phpunit": "^7.5.20", + "phpunit/phpunit": "^8.5", "spatie/phpunit-watcher": "^1.23" }, "require": { diff --git a/composer.lock b/composer.lock index bff5a02fc188c0..5a0d86e54a1bdb 100644 --- a/composer.lock +++ b/composer.lock @@ -4,20 +4,20 @@ "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies", "This file is @generated automatically" ], - "content-hash": "a0cee819dff559c9839fd0e98cb4186a", + "content-hash": "1072fbf86d89fdd06d9702e33d12d114", "packages": [ { "name": "composer/installers", - "version": "v1.9.0", + "version": "v1.10.0", "source": { "type": "git", "url": "https://github.com/composer/installers.git", - "reference": "b93bcf0fa1fccb0b7d176b0967d969691cd74cca" + "reference": "1a0357fccad9d1cc1ea0c9a05b8847fbccccb78d" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/composer/installers/zipball/b93bcf0fa1fccb0b7d176b0967d969691cd74cca", - "reference": "b93bcf0fa1fccb0b7d176b0967d969691cd74cca", + "url": "https://api.github.com/repos/composer/installers/zipball/1a0357fccad9d1cc1ea0c9a05b8847fbccccb78d", + "reference": "1a0357fccad9d1cc1ea0c9a05b8847fbccccb78d", "shasum": "" }, "require": { @@ -28,17 +28,18 @@ "shama/baton": "*" }, "require-dev": { - "composer/composer": "1.6.* || 2.0.*@dev", - "composer/semver": "1.0.* || 2.0.*@dev", - "phpunit/phpunit": "^4.8.36", - "sebastian/comparator": "^1.2.4", + "composer/composer": "1.6.* || ^2.0", + "composer/semver": "^1 || ^3", + "phpstan/phpstan": "^0.12.55", + "phpstan/phpstan-phpunit": "^0.12.16", + "symfony/phpunit-bridge": "^4.2 || ^5", "symfony/process": "^2.3" }, "type": "composer-plugin", "extra": { "class": "Composer\\Installers\\Plugin", "branch-alias": { - "dev-master": "1.0-dev" + "dev-main": "1.x-dev" } }, "autoload": { @@ -76,6 +77,7 @@ "Porto", "RadPHP", "SMF", + "Starbug", "Thelia", "Whmcs", "WolfCMS", @@ -116,6 +118,7 @@ "phpbb", "piwik", "ppi", + "processwire", "puppet", "pxcms", "reindex", @@ -131,32 +134,40 @@ "zend", "zikula" ], + "support": { + "issues": "https://github.com/composer/installers/issues", + "source": "https://github.com/composer/installers/tree/v1.10.0" + }, "funding": [ { "url": "https://packagist.com", "type": "custom" }, + { + "url": "https://github.com/composer", + "type": "github" + }, { "url": "https://tidelift.com/funding/github/packagist/composer/composer", "type": "tidelift" } ], - "time": "2020-04-07T06:57:05+00:00" + "time": "2021-01-14T11:07:16+00:00" } ], "packages-dev": [ { "name": "clue/stdio-react", - "version": "v2.3.0", + "version": "v2.4.0", "source": { "type": "git", "url": "https://github.com/clue/reactphp-stdio.git", - "reference": "5f42a3a5a29f52432f0f68b57890353e8ca65069" + "reference": "5722686d3cc0cdf2ccedb6079bfd066220611f00" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/clue/reactphp-stdio/zipball/5f42a3a5a29f52432f0f68b57890353e8ca65069", - "reference": "5f42a3a5a29f52432f0f68b57890353e8ca65069", + "url": "https://api.github.com/repos/clue/reactphp-stdio/zipball/5722686d3cc0cdf2ccedb6079bfd066220611f00", + "reference": "5722686d3cc0cdf2ccedb6079bfd066220611f00", "shasum": "" }, "require": { @@ -169,7 +180,7 @@ "require-dev": { "clue/arguments": "^2.0", "clue/commander": "^1.2", - "phpunit/phpunit": "^7.0 || ^6.4 || ^5.7 || ^4.8.35" + "phpunit/phpunit": "^9.3 || ^5.7 || ^4.8.35" }, "suggest": { "ext-mbstring": "Using ext-mbstring should provide slightly better performance for handling I/O" @@ -187,7 +198,7 @@ "authors": [ { "name": "Christian Lück", - "email": "christian@lueck.tv" + "email": "christian@clue.engineering" } ], "description": "Async, event-driven console input & output (STDIN, STDOUT) for truly interactive CLI applications, built on top of ReactPHP", @@ -205,7 +216,21 @@ "stdio", "stdout" ], - "time": "2019-08-28T12:01:30+00:00" + "support": { + "issues": "https://github.com/clue/reactphp-stdio/issues", + "source": "https://github.com/clue/reactphp-stdio/tree/v2.4.0" + }, + "funding": [ + { + "url": "https://clue.engineering/support", + "type": "custom" + }, + { + "url": "https://github.com/clue", + "type": "github" + } + ], + "time": "2020-11-20T14:28:39+00:00" }, { "name": "clue/term-react", @@ -264,6 +289,10 @@ "vt100", "xterm" ], + "support": { + "issues": "https://github.com/clue/reactphp-term/issues", + "source": "https://github.com/clue/reactphp-term/tree/v1.3.0" + }, "funding": [ { "url": "https://clue.engineering/support", @@ -323,6 +352,10 @@ "utf-8", "utf8" ], + "support": { + "issues": "https://github.com/clue/reactphp-utf8/issues", + "source": "https://github.com/clue/reactphp-utf8/tree/v1.2.0" + }, "funding": [ { "url": "https://clue.engineering/support", @@ -337,22 +370,22 @@ }, { "name": "dealerdirect/phpcodesniffer-composer-installer", - "version": "v0.7.0", + "version": "v0.7.1", "source": { "type": "git", "url": "https://github.com/Dealerdirect/phpcodesniffer-composer-installer.git", - "reference": "e8d808670b8f882188368faaf1144448c169c0b7" + "reference": "fe390591e0241955f22eb9ba327d137e501c771c" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/Dealerdirect/phpcodesniffer-composer-installer/zipball/e8d808670b8f882188368faaf1144448c169c0b7", - "reference": "e8d808670b8f882188368faaf1144448c169c0b7", + "url": "https://api.github.com/repos/Dealerdirect/phpcodesniffer-composer-installer/zipball/fe390591e0241955f22eb9ba327d137e501c771c", + "reference": "fe390591e0241955f22eb9ba327d137e501c771c", "shasum": "" }, "require": { "composer-plugin-api": "^1.0 || ^2.0", "php": ">=5.3", - "squizlabs/php_codesniffer": "^2 || ^3 || 4.0.x-dev" + "squizlabs/php_codesniffer": "^2.0 || ^3.0 || ^4.0" }, "require-dev": { "composer/composer": "*", @@ -399,7 +432,11 @@ "stylecheck", "tests" ], - "time": "2020-06-25T14:57:39+00:00" + "support": { + "issues": "https://github.com/dealerdirect/phpcodesniffer-composer-installer/issues", + "source": "https://github.com/dealerdirect/phpcodesniffer-composer-installer" + }, + "time": "2020-12-07T18:04:37+00:00" }, { "name": "doctrine/instantiator", @@ -450,6 +487,10 @@ "constructor", "instantiate" ], + "support": { + "issues": "https://github.com/doctrine/instantiator/issues", + "source": "https://github.com/doctrine/instantiator/tree/1.4.0" + }, "funding": [ { "url": "https://www.doctrine-project.org/sponsorship.html", @@ -507,6 +548,10 @@ "event-dispatcher", "event-emitter" ], + "support": { + "issues": "https://github.com/igorw/evenement/issues", + "source": "https://github.com/igorw/evenement/tree/master" + }, "time": "2017-07-23T21:35:13+00:00" }, { @@ -564,6 +609,10 @@ "notification", "windows" ], + "support": { + "issues": "https://github.com/jolicode/JoliNotif/issues", + "source": "https://github.com/jolicode/JoliNotif/tree/v2.2.0" + }, "funding": [ { "url": "https://tidelift.com/funding/github/packagist/jolicode/jolinotif", @@ -618,6 +667,10 @@ "object", "object graph" ], + "support": { + "issues": "https://github.com/myclabs/DeepCopy/issues", + "source": "https://github.com/myclabs/DeepCopy/tree/1.10.2" + }, "funding": [ { "url": "https://tidelift.com/funding/github/packagist/myclabs/deep-copy", @@ -628,28 +681,29 @@ }, { "name": "phar-io/manifest", - "version": "1.0.3", + "version": "2.0.1", "source": { "type": "git", "url": "https://github.com/phar-io/manifest.git", - "reference": "7761fcacf03b4d4f16e7ccb606d4879ca431fcf4" + "reference": "85265efd3af7ba3ca4b2a2c34dbfc5788dd29133" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/phar-io/manifest/zipball/7761fcacf03b4d4f16e7ccb606d4879ca431fcf4", - "reference": "7761fcacf03b4d4f16e7ccb606d4879ca431fcf4", + "url": "https://api.github.com/repos/phar-io/manifest/zipball/85265efd3af7ba3ca4b2a2c34dbfc5788dd29133", + "reference": "85265efd3af7ba3ca4b2a2c34dbfc5788dd29133", "shasum": "" }, "require": { "ext-dom": "*", "ext-phar": "*", - "phar-io/version": "^2.0", - "php": "^5.6 || ^7.0" + "ext-xmlwriter": "*", + "phar-io/version": "^3.0.1", + "php": "^7.2 || ^8.0" }, "type": "library", "extra": { "branch-alias": { - "dev-master": "1.0.x-dev" + "dev-master": "2.0.x-dev" } }, "autoload": { @@ -679,24 +733,28 @@ } ], "description": "Component for reading phar.io manifest information from a PHP Archive (PHAR)", - "time": "2018-07-08T19:23:20+00:00" + "support": { + "issues": "https://github.com/phar-io/manifest/issues", + "source": "https://github.com/phar-io/manifest/tree/master" + }, + "time": "2020-06-27T14:33:11+00:00" }, { "name": "phar-io/version", - "version": "2.0.1", + "version": "3.0.4", "source": { "type": "git", "url": "https://github.com/phar-io/version.git", - "reference": "45a2ec53a73c70ce41d55cedef9063630abaf1b6" + "reference": "e4782611070e50613683d2b9a57730e9a3ba5451" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/phar-io/version/zipball/45a2ec53a73c70ce41d55cedef9063630abaf1b6", - "reference": "45a2ec53a73c70ce41d55cedef9063630abaf1b6", + "url": "https://api.github.com/repos/phar-io/version/zipball/e4782611070e50613683d2b9a57730e9a3ba5451", + "reference": "e4782611070e50613683d2b9a57730e9a3ba5451", "shasum": "" }, "require": { - "php": "^5.6 || ^7.0" + "php": "^7.2 || ^8.0" }, "type": "library", "autoload": { @@ -726,7 +784,11 @@ } ], "description": "Library for handling version information and constraints", - "time": "2018-07-08T19:19:57+00:00" + "support": { + "issues": "https://github.com/phar-io/version/issues", + "source": "https://github.com/phar-io/version/tree/3.0.4" + }, + "time": "2020-12-13T23:18:30+00:00" }, { "name": "phpcompatibility/php-compatibility", @@ -784,6 +846,10 @@ "phpcs", "standards" ], + "support": { + "issues": "https://github.com/PHPCompatibility/PHPCompatibility/issues", + "source": "https://github.com/PHPCompatibility/PHPCompatibility" + }, "time": "2019-12-27T09:44:58+00:00" }, { @@ -833,6 +899,10 @@ "reflection", "static analysis" ], + "support": { + "issues": "https://github.com/phpDocumentor/ReflectionCommon/issues", + "source": "https://github.com/phpDocumentor/ReflectionCommon/tree/2.x" + }, "time": "2020-06-27T09:03:43+00:00" }, { @@ -885,6 +955,10 @@ } ], "description": "With this component, a library can provide support for annotations via DocBlocks or otherwise retrieve information that is embedded in a DocBlock.", + "support": { + "issues": "https://github.com/phpDocumentor/ReflectionDocBlock/issues", + "source": "https://github.com/phpDocumentor/ReflectionDocBlock/tree/master" + }, "time": "2020-09-03T19:13:55+00:00" }, { @@ -930,20 +1004,24 @@ } ], "description": "A PSR-5 based resolver of Class names, Types and Structural Element Names", + "support": { + "issues": "https://github.com/phpDocumentor/TypeResolver/issues", + "source": "https://github.com/phpDocumentor/TypeResolver/tree/1.4.0" + }, "time": "2020-09-17T18:55:26+00:00" }, { "name": "phpspec/prophecy", - "version": "1.12.1", + "version": "1.12.2", "source": { "type": "git", "url": "https://github.com/phpspec/prophecy.git", - "reference": "8ce87516be71aae9b956f81906aaf0338e0d8a2d" + "reference": "245710e971a030f42e08f4912863805570f23d39" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/phpspec/prophecy/zipball/8ce87516be71aae9b956f81906aaf0338e0d8a2d", - "reference": "8ce87516be71aae9b956f81906aaf0338e0d8a2d", + "url": "https://api.github.com/repos/phpspec/prophecy/zipball/245710e971a030f42e08f4912863805570f23d39", + "reference": "245710e971a030f42e08f4912863805570f23d39", "shasum": "" }, "require": { @@ -955,7 +1033,7 @@ }, "require-dev": { "phpspec/phpspec": "^6.0", - "phpunit/phpunit": "^8.0 || ^9.0 <9.3" + "phpunit/phpunit": "^8.0 || ^9.0" }, "type": "library", "extra": { @@ -993,44 +1071,48 @@ "spy", "stub" ], - "time": "2020-09-29T09:10:42+00:00" + "support": { + "issues": "https://github.com/phpspec/prophecy/issues", + "source": "https://github.com/phpspec/prophecy/tree/1.12.2" + }, + "time": "2020-12-19T10:15:11+00:00" }, { "name": "phpunit/php-code-coverage", - "version": "6.1.4", + "version": "7.0.14", "source": { "type": "git", "url": "https://github.com/sebastianbergmann/php-code-coverage.git", - "reference": "807e6013b00af69b6c5d9ceb4282d0393dbb9d8d" + "reference": "bb7c9a210c72e4709cdde67f8b7362f672f2225c" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/sebastianbergmann/php-code-coverage/zipball/807e6013b00af69b6c5d9ceb4282d0393dbb9d8d", - "reference": "807e6013b00af69b6c5d9ceb4282d0393dbb9d8d", + "url": "https://api.github.com/repos/sebastianbergmann/php-code-coverage/zipball/bb7c9a210c72e4709cdde67f8b7362f672f2225c", + "reference": "bb7c9a210c72e4709cdde67f8b7362f672f2225c", "shasum": "" }, "require": { "ext-dom": "*", "ext-xmlwriter": "*", - "php": "^7.1", - "phpunit/php-file-iterator": "^2.0", + "php": ">=7.2", + "phpunit/php-file-iterator": "^2.0.2", "phpunit/php-text-template": "^1.2.1", - "phpunit/php-token-stream": "^3.0", + "phpunit/php-token-stream": "^3.1.1 || ^4.0", "sebastian/code-unit-reverse-lookup": "^1.0.1", - "sebastian/environment": "^3.1 || ^4.0", + "sebastian/environment": "^4.2.2", "sebastian/version": "^2.0.1", - "theseer/tokenizer": "^1.1" + "theseer/tokenizer": "^1.1.3" }, "require-dev": { - "phpunit/phpunit": "^7.0" + "phpunit/phpunit": "^8.2.2" }, "suggest": { - "ext-xdebug": "^2.6.0" + "ext-xdebug": "^2.7.2" }, "type": "library", "extra": { "branch-alias": { - "dev-master": "6.1-dev" + "dev-master": "7.0-dev" } }, "autoload": { @@ -1056,27 +1138,37 @@ "testing", "xunit" ], - "time": "2018-10-31T16:06:48+00:00" + "support": { + "issues": "https://github.com/sebastianbergmann/php-code-coverage/issues", + "source": "https://github.com/sebastianbergmann/php-code-coverage/tree/7.0.14" + }, + "funding": [ + { + "url": "https://github.com/sebastianbergmann", + "type": "github" + } + ], + "time": "2020-12-02T13:39:03+00:00" }, { "name": "phpunit/php-file-iterator", - "version": "2.0.2", + "version": "2.0.3", "source": { "type": "git", "url": "https://github.com/sebastianbergmann/php-file-iterator.git", - "reference": "050bedf145a257b1ff02746c31894800e5122946" + "reference": "4b49fb70f067272b659ef0174ff9ca40fdaa6357" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/sebastianbergmann/php-file-iterator/zipball/050bedf145a257b1ff02746c31894800e5122946", - "reference": "050bedf145a257b1ff02746c31894800e5122946", + "url": "https://api.github.com/repos/sebastianbergmann/php-file-iterator/zipball/4b49fb70f067272b659ef0174ff9ca40fdaa6357", + "reference": "4b49fb70f067272b659ef0174ff9ca40fdaa6357", "shasum": "" }, "require": { - "php": "^7.1" + "php": ">=7.1" }, "require-dev": { - "phpunit/phpunit": "^7.1" + "phpunit/phpunit": "^8.5" }, "type": "library", "extra": { @@ -1106,7 +1198,17 @@ "filesystem", "iterator" ], - "time": "2018-09-13T20:33:42+00:00" + "support": { + "issues": "https://github.com/sebastianbergmann/php-file-iterator/issues", + "source": "https://github.com/sebastianbergmann/php-file-iterator/tree/2.0.3" + }, + "funding": [ + { + "url": "https://github.com/sebastianbergmann", + "type": "github" + } + ], + "time": "2020-11-30T08:25:21+00:00" }, { "name": "phpunit/php-text-template", @@ -1147,27 +1249,31 @@ "keywords": [ "template" ], + "support": { + "issues": "https://github.com/sebastianbergmann/php-text-template/issues", + "source": "https://github.com/sebastianbergmann/php-text-template/tree/1.2.1" + }, "time": "2015-06-21T13:50:34+00:00" }, { "name": "phpunit/php-timer", - "version": "2.1.2", + "version": "2.1.3", "source": { "type": "git", "url": "https://github.com/sebastianbergmann/php-timer.git", - "reference": "1038454804406b0b5f5f520358e78c1c2f71501e" + "reference": "2454ae1765516d20c4ffe103d85a58a9a3bd5662" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/sebastianbergmann/php-timer/zipball/1038454804406b0b5f5f520358e78c1c2f71501e", - "reference": "1038454804406b0b5f5f520358e78c1c2f71501e", + "url": "https://api.github.com/repos/sebastianbergmann/php-timer/zipball/2454ae1765516d20c4ffe103d85a58a9a3bd5662", + "reference": "2454ae1765516d20c4ffe103d85a58a9a3bd5662", "shasum": "" }, "require": { - "php": "^7.1" + "php": ">=7.1" }, "require-dev": { - "phpunit/phpunit": "^7.0" + "phpunit/phpunit": "^8.5" }, "type": "library", "extra": { @@ -1196,33 +1302,43 @@ "keywords": [ "timer" ], - "time": "2019-06-07T04:22:29+00:00" + "support": { + "issues": "https://github.com/sebastianbergmann/php-timer/issues", + "source": "https://github.com/sebastianbergmann/php-timer/tree/2.1.3" + }, + "funding": [ + { + "url": "https://github.com/sebastianbergmann", + "type": "github" + } + ], + "time": "2020-11-30T08:20:02+00:00" }, { "name": "phpunit/php-token-stream", - "version": "3.1.1", + "version": "4.0.4", "source": { "type": "git", "url": "https://github.com/sebastianbergmann/php-token-stream.git", - "reference": "995192df77f63a59e47f025390d2d1fdf8f425ff" + "reference": "a853a0e183b9db7eed023d7933a858fa1c8d25a3" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/sebastianbergmann/php-token-stream/zipball/995192df77f63a59e47f025390d2d1fdf8f425ff", - "reference": "995192df77f63a59e47f025390d2d1fdf8f425ff", + "url": "https://api.github.com/repos/sebastianbergmann/php-token-stream/zipball/a853a0e183b9db7eed023d7933a858fa1c8d25a3", + "reference": "a853a0e183b9db7eed023d7933a858fa1c8d25a3", "shasum": "" }, "require": { "ext-tokenizer": "*", - "php": "^7.1" + "php": "^7.3 || ^8.0" }, "require-dev": { - "phpunit/phpunit": "^7.0" + "phpunit/phpunit": "^9.0" }, "type": "library", "extra": { "branch-alias": { - "dev-master": "3.1-dev" + "dev-master": "4.0-dev" } }, "autoload": { @@ -1245,58 +1361,67 @@ "keywords": [ "tokenizer" ], + "support": { + "issues": "https://github.com/sebastianbergmann/php-token-stream/issues", + "source": "https://github.com/sebastianbergmann/php-token-stream/tree/master" + }, + "funding": [ + { + "url": "https://github.com/sebastianbergmann", + "type": "github" + } + ], "abandoned": true, - "time": "2019-09-17T06:23:10+00:00" + "time": "2020-08-04T08:28:15+00:00" }, { "name": "phpunit/phpunit", - "version": "7.5.20", + "version": "8.5.14", "source": { "type": "git", "url": "https://github.com/sebastianbergmann/phpunit.git", - "reference": "9467db479d1b0487c99733bb1e7944d32deded2c" + "reference": "c25f79895d27b6ecd5abfa63de1606b786a461a3" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/sebastianbergmann/phpunit/zipball/9467db479d1b0487c99733bb1e7944d32deded2c", - "reference": "9467db479d1b0487c99733bb1e7944d32deded2c", + "url": "https://api.github.com/repos/sebastianbergmann/phpunit/zipball/c25f79895d27b6ecd5abfa63de1606b786a461a3", + "reference": "c25f79895d27b6ecd5abfa63de1606b786a461a3", "shasum": "" }, "require": { - "doctrine/instantiator": "^1.1", + "doctrine/instantiator": "^1.3.1", "ext-dom": "*", "ext-json": "*", "ext-libxml": "*", "ext-mbstring": "*", "ext-xml": "*", - "myclabs/deep-copy": "^1.7", - "phar-io/manifest": "^1.0.2", - "phar-io/version": "^2.0", - "php": "^7.1", - "phpspec/prophecy": "^1.7", - "phpunit/php-code-coverage": "^6.0.7", - "phpunit/php-file-iterator": "^2.0.1", + "ext-xmlwriter": "*", + "myclabs/deep-copy": "^1.10.0", + "phar-io/manifest": "^2.0.1", + "phar-io/version": "^3.0.2", + "php": ">=7.2", + "phpspec/prophecy": "^1.10.3", + "phpunit/php-code-coverage": "^7.0.12", + "phpunit/php-file-iterator": "^2.0.2", "phpunit/php-text-template": "^1.2.1", - "phpunit/php-timer": "^2.1", - "sebastian/comparator": "^3.0", - "sebastian/diff": "^3.0", - "sebastian/environment": "^4.0", - "sebastian/exporter": "^3.1", - "sebastian/global-state": "^2.0", + "phpunit/php-timer": "^2.1.2", + "sebastian/comparator": "^3.0.2", + "sebastian/diff": "^3.0.2", + "sebastian/environment": "^4.2.3", + "sebastian/exporter": "^3.1.2", + "sebastian/global-state": "^3.0.0", "sebastian/object-enumerator": "^3.0.3", - "sebastian/resource-operations": "^2.0", + "sebastian/resource-operations": "^2.0.1", + "sebastian/type": "^1.1.3", "sebastian/version": "^2.0.1" }, - "conflict": { - "phpunit/phpunit-mock-objects": "*" - }, "require-dev": { "ext-pdo": "*" }, "suggest": { "ext-soap": "*", "ext-xdebug": "*", - "phpunit/php-invoker": "^2.0" + "phpunit/php-invoker": "^2.0.0" }, "bin": [ "phpunit" @@ -1304,7 +1429,7 @@ "type": "library", "extra": { "branch-alias": { - "dev-master": "7.5-dev" + "dev-master": "8.5-dev" } }, "autoload": { @@ -1330,7 +1455,21 @@ "testing", "xunit" ], - "time": "2020-01-08T08:45:45+00:00" + "support": { + "issues": "https://github.com/sebastianbergmann/phpunit/issues", + "source": "https://github.com/sebastianbergmann/phpunit/tree/8.5.14" + }, + "funding": [ + { + "url": "https://phpunit.de/donate.html", + "type": "custom" + }, + { + "url": "https://github.com/sebastianbergmann", + "type": "github" + } + ], + "time": "2021-01-17T07:37:30+00:00" }, { "name": "psr/container", @@ -1379,6 +1518,10 @@ "container-interop", "psr" ], + "support": { + "issues": "https://github.com/php-fig/container/issues", + "source": "https://github.com/php-fig/container/tree/master" + }, "time": "2017-02-14T16:28:37+00:00" }, { @@ -1421,6 +1564,10 @@ "asynchronous", "event-loop" ], + "support": { + "issues": "https://github.com/reactphp/event-loop/issues", + "source": "https://github.com/reactphp/event-loop/tree/v1.1.1" + }, "time": "2020-01-01T18:39:52+00:00" }, { @@ -1467,27 +1614,31 @@ "stream", "writable" ], + "support": { + "issues": "https://github.com/reactphp/stream/issues", + "source": "https://github.com/reactphp/stream/tree/v1.1.1" + }, "time": "2020-05-04T10:17:57+00:00" }, { "name": "sebastian/code-unit-reverse-lookup", - "version": "1.0.1", + "version": "1.0.2", "source": { "type": "git", "url": "https://github.com/sebastianbergmann/code-unit-reverse-lookup.git", - "reference": "4419fcdb5eabb9caa61a27c7a1db532a6b55dd18" + "reference": "1de8cd5c010cb153fcd68b8d0f64606f523f7619" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/sebastianbergmann/code-unit-reverse-lookup/zipball/4419fcdb5eabb9caa61a27c7a1db532a6b55dd18", - "reference": "4419fcdb5eabb9caa61a27c7a1db532a6b55dd18", + "url": "https://api.github.com/repos/sebastianbergmann/code-unit-reverse-lookup/zipball/1de8cd5c010cb153fcd68b8d0f64606f523f7619", + "reference": "1de8cd5c010cb153fcd68b8d0f64606f523f7619", "shasum": "" }, "require": { - "php": "^5.6 || ^7.0" + "php": ">=5.6" }, "require-dev": { - "phpunit/phpunit": "^5.7 || ^6.0" + "phpunit/phpunit": "^8.5" }, "type": "library", "extra": { @@ -1512,29 +1663,39 @@ ], "description": "Looks up which function or method a line of code belongs to", "homepage": "https://github.com/sebastianbergmann/code-unit-reverse-lookup/", - "time": "2017-03-04T06:30:41+00:00" + "support": { + "issues": "https://github.com/sebastianbergmann/code-unit-reverse-lookup/issues", + "source": "https://github.com/sebastianbergmann/code-unit-reverse-lookup/tree/1.0.2" + }, + "funding": [ + { + "url": "https://github.com/sebastianbergmann", + "type": "github" + } + ], + "time": "2020-11-30T08:15:22+00:00" }, { "name": "sebastian/comparator", - "version": "3.0.2", + "version": "3.0.3", "source": { "type": "git", "url": "https://github.com/sebastianbergmann/comparator.git", - "reference": "5de4fc177adf9bce8df98d8d141a7559d7ccf6da" + "reference": "1071dfcef776a57013124ff35e1fc41ccd294758" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/sebastianbergmann/comparator/zipball/5de4fc177adf9bce8df98d8d141a7559d7ccf6da", - "reference": "5de4fc177adf9bce8df98d8d141a7559d7ccf6da", + "url": "https://api.github.com/repos/sebastianbergmann/comparator/zipball/1071dfcef776a57013124ff35e1fc41ccd294758", + "reference": "1071dfcef776a57013124ff35e1fc41ccd294758", "shasum": "" }, "require": { - "php": "^7.1", + "php": ">=7.1", "sebastian/diff": "^3.0", "sebastian/exporter": "^3.1" }, "require-dev": { - "phpunit/phpunit": "^7.1" + "phpunit/phpunit": "^8.5" }, "type": "library", "extra": { @@ -1552,6 +1713,10 @@ "BSD-3-Clause" ], "authors": [ + { + "name": "Sebastian Bergmann", + "email": "sebastian@phpunit.de" + }, { "name": "Jeff Welch", "email": "whatthejeff@gmail.com" @@ -1563,10 +1728,6 @@ { "name": "Bernhard Schussek", "email": "bschussek@2bepublished.at" - }, - { - "name": "Sebastian Bergmann", - "email": "sebastian@phpunit.de" } ], "description": "Provides the functionality to compare PHP values for equality", @@ -1576,24 +1737,34 @@ "compare", "equality" ], - "time": "2018-07-12T15:12:46+00:00" + "support": { + "issues": "https://github.com/sebastianbergmann/comparator/issues", + "source": "https://github.com/sebastianbergmann/comparator/tree/3.0.3" + }, + "funding": [ + { + "url": "https://github.com/sebastianbergmann", + "type": "github" + } + ], + "time": "2020-11-30T08:04:30+00:00" }, { "name": "sebastian/diff", - "version": "3.0.2", + "version": "3.0.3", "source": { "type": "git", "url": "https://github.com/sebastianbergmann/diff.git", - "reference": "720fcc7e9b5cf384ea68d9d930d480907a0c1a29" + "reference": "14f72dd46eaf2f2293cbe79c93cc0bc43161a211" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/sebastianbergmann/diff/zipball/720fcc7e9b5cf384ea68d9d930d480907a0c1a29", - "reference": "720fcc7e9b5cf384ea68d9d930d480907a0c1a29", + "url": "https://api.github.com/repos/sebastianbergmann/diff/zipball/14f72dd46eaf2f2293cbe79c93cc0bc43161a211", + "reference": "14f72dd46eaf2f2293cbe79c93cc0bc43161a211", "shasum": "" }, "require": { - "php": "^7.1" + "php": ">=7.1" }, "require-dev": { "phpunit/phpunit": "^7.5 || ^8.0", @@ -1615,13 +1786,13 @@ "BSD-3-Clause" ], "authors": [ - { - "name": "Kore Nordmann", - "email": "mail@kore-nordmann.de" - }, { "name": "Sebastian Bergmann", "email": "sebastian@phpunit.de" + }, + { + "name": "Kore Nordmann", + "email": "mail@kore-nordmann.de" } ], "description": "Diff implementation", @@ -1632,24 +1803,34 @@ "unidiff", "unified diff" ], - "time": "2019-02-04T06:01:07+00:00" + "support": { + "issues": "https://github.com/sebastianbergmann/diff/issues", + "source": "https://github.com/sebastianbergmann/diff/tree/3.0.3" + }, + "funding": [ + { + "url": "https://github.com/sebastianbergmann", + "type": "github" + } + ], + "time": "2020-11-30T07:59:04+00:00" }, { "name": "sebastian/environment", - "version": "4.2.3", + "version": "4.2.4", "source": { "type": "git", "url": "https://github.com/sebastianbergmann/environment.git", - "reference": "464c90d7bdf5ad4e8a6aea15c091fec0603d4368" + "reference": "d47bbbad83711771f167c72d4e3f25f7fcc1f8b0" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/sebastianbergmann/environment/zipball/464c90d7bdf5ad4e8a6aea15c091fec0603d4368", - "reference": "464c90d7bdf5ad4e8a6aea15c091fec0603d4368", + "url": "https://api.github.com/repos/sebastianbergmann/environment/zipball/d47bbbad83711771f167c72d4e3f25f7fcc1f8b0", + "reference": "d47bbbad83711771f167c72d4e3f25f7fcc1f8b0", "shasum": "" }, "require": { - "php": "^7.1" + "php": ">=7.1" }, "require-dev": { "phpunit/phpunit": "^7.5" @@ -1685,24 +1866,34 @@ "environment", "hhvm" ], - "time": "2019-11-20T08:46:58+00:00" + "support": { + "issues": "https://github.com/sebastianbergmann/environment/issues", + "source": "https://github.com/sebastianbergmann/environment/tree/4.2.4" + }, + "funding": [ + { + "url": "https://github.com/sebastianbergmann", + "type": "github" + } + ], + "time": "2020-11-30T07:53:42+00:00" }, { "name": "sebastian/exporter", - "version": "3.1.2", + "version": "3.1.3", "source": { "type": "git", "url": "https://github.com/sebastianbergmann/exporter.git", - "reference": "68609e1261d215ea5b21b7987539cbfbe156ec3e" + "reference": "6b853149eab67d4da22291d36f5b0631c0fd856e" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/sebastianbergmann/exporter/zipball/68609e1261d215ea5b21b7987539cbfbe156ec3e", - "reference": "68609e1261d215ea5b21b7987539cbfbe156ec3e", + "url": "https://api.github.com/repos/sebastianbergmann/exporter/zipball/6b853149eab67d4da22291d36f5b0631c0fd856e", + "reference": "6b853149eab67d4da22291d36f5b0631c0fd856e", "shasum": "" }, "require": { - "php": "^7.0", + "php": ">=7.0", "sebastian/recursion-context": "^3.0" }, "require-dev": { @@ -1752,27 +1943,40 @@ "export", "exporter" ], - "time": "2019-09-14T09:02:43+00:00" + "support": { + "issues": "https://github.com/sebastianbergmann/exporter/issues", + "source": "https://github.com/sebastianbergmann/exporter/tree/3.1.3" + }, + "funding": [ + { + "url": "https://github.com/sebastianbergmann", + "type": "github" + } + ], + "time": "2020-11-30T07:47:53+00:00" }, { "name": "sebastian/global-state", - "version": "2.0.0", + "version": "3.0.1", "source": { "type": "git", "url": "https://github.com/sebastianbergmann/global-state.git", - "reference": "e8ba02eed7bbbb9e59e43dedd3dddeff4a56b0c4" + "reference": "474fb9edb7ab891665d3bfc6317f42a0a150454b" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/sebastianbergmann/global-state/zipball/e8ba02eed7bbbb9e59e43dedd3dddeff4a56b0c4", - "reference": "e8ba02eed7bbbb9e59e43dedd3dddeff4a56b0c4", + "url": "https://api.github.com/repos/sebastianbergmann/global-state/zipball/474fb9edb7ab891665d3bfc6317f42a0a150454b", + "reference": "474fb9edb7ab891665d3bfc6317f42a0a150454b", "shasum": "" }, "require": { - "php": "^7.0" + "php": ">=7.2", + "sebastian/object-reflector": "^1.1.1", + "sebastian/recursion-context": "^3.0" }, "require-dev": { - "phpunit/phpunit": "^6.0" + "ext-dom": "*", + "phpunit/phpunit": "^8.0" }, "suggest": { "ext-uopz": "*" @@ -1780,7 +1984,7 @@ "type": "library", "extra": { "branch-alias": { - "dev-master": "2.0-dev" + "dev-master": "3.0-dev" } }, "autoload": { @@ -1803,24 +2007,34 @@ "keywords": [ "global state" ], - "time": "2017-04-27T15:39:26+00:00" + "support": { + "issues": "https://github.com/sebastianbergmann/global-state/issues", + "source": "https://github.com/sebastianbergmann/global-state/tree/3.0.1" + }, + "funding": [ + { + "url": "https://github.com/sebastianbergmann", + "type": "github" + } + ], + "time": "2020-11-30T07:43:24+00:00" }, { "name": "sebastian/object-enumerator", - "version": "3.0.3", + "version": "3.0.4", "source": { "type": "git", "url": "https://github.com/sebastianbergmann/object-enumerator.git", - "reference": "7cfd9e65d11ffb5af41198476395774d4c8a84c5" + "reference": "e67f6d32ebd0c749cf9d1dbd9f226c727043cdf2" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/sebastianbergmann/object-enumerator/zipball/7cfd9e65d11ffb5af41198476395774d4c8a84c5", - "reference": "7cfd9e65d11ffb5af41198476395774d4c8a84c5", + "url": "https://api.github.com/repos/sebastianbergmann/object-enumerator/zipball/e67f6d32ebd0c749cf9d1dbd9f226c727043cdf2", + "reference": "e67f6d32ebd0c749cf9d1dbd9f226c727043cdf2", "shasum": "" }, "require": { - "php": "^7.0", + "php": ">=7.0", "sebastian/object-reflector": "^1.1.1", "sebastian/recursion-context": "^3.0" }, @@ -1850,24 +2064,34 @@ ], "description": "Traverses array structures and object graphs to enumerate all referenced objects", "homepage": "https://github.com/sebastianbergmann/object-enumerator/", - "time": "2017-08-03T12:35:26+00:00" + "support": { + "issues": "https://github.com/sebastianbergmann/object-enumerator/issues", + "source": "https://github.com/sebastianbergmann/object-enumerator/tree/3.0.4" + }, + "funding": [ + { + "url": "https://github.com/sebastianbergmann", + "type": "github" + } + ], + "time": "2020-11-30T07:40:27+00:00" }, { "name": "sebastian/object-reflector", - "version": "1.1.1", + "version": "1.1.2", "source": { "type": "git", "url": "https://github.com/sebastianbergmann/object-reflector.git", - "reference": "773f97c67f28de00d397be301821b06708fca0be" + "reference": "9b8772b9cbd456ab45d4a598d2dd1a1bced6363d" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/sebastianbergmann/object-reflector/zipball/773f97c67f28de00d397be301821b06708fca0be", - "reference": "773f97c67f28de00d397be301821b06708fca0be", + "url": "https://api.github.com/repos/sebastianbergmann/object-reflector/zipball/9b8772b9cbd456ab45d4a598d2dd1a1bced6363d", + "reference": "9b8772b9cbd456ab45d4a598d2dd1a1bced6363d", "shasum": "" }, "require": { - "php": "^7.0" + "php": ">=7.0" }, "require-dev": { "phpunit/phpunit": "^6.0" @@ -1895,24 +2119,34 @@ ], "description": "Allows reflection of object attributes, including inherited and non-public ones", "homepage": "https://github.com/sebastianbergmann/object-reflector/", - "time": "2017-03-29T09:07:27+00:00" + "support": { + "issues": "https://github.com/sebastianbergmann/object-reflector/issues", + "source": "https://github.com/sebastianbergmann/object-reflector/tree/1.1.2" + }, + "funding": [ + { + "url": "https://github.com/sebastianbergmann", + "type": "github" + } + ], + "time": "2020-11-30T07:37:18+00:00" }, { "name": "sebastian/recursion-context", - "version": "3.0.0", + "version": "3.0.1", "source": { "type": "git", "url": "https://github.com/sebastianbergmann/recursion-context.git", - "reference": "5b0cd723502bac3b006cbf3dbf7a1e3fcefe4fa8" + "reference": "367dcba38d6e1977be014dc4b22f47a484dac7fb" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/sebastianbergmann/recursion-context/zipball/5b0cd723502bac3b006cbf3dbf7a1e3fcefe4fa8", - "reference": "5b0cd723502bac3b006cbf3dbf7a1e3fcefe4fa8", + "url": "https://api.github.com/repos/sebastianbergmann/recursion-context/zipball/367dcba38d6e1977be014dc4b22f47a484dac7fb", + "reference": "367dcba38d6e1977be014dc4b22f47a484dac7fb", "shasum": "" }, "require": { - "php": "^7.0" + "php": ">=7.0" }, "require-dev": { "phpunit/phpunit": "^6.0" @@ -1933,14 +2167,14 @@ "BSD-3-Clause" ], "authors": [ - { - "name": "Jeff Welch", - "email": "whatthejeff@gmail.com" - }, { "name": "Sebastian Bergmann", "email": "sebastian@phpunit.de" }, + { + "name": "Jeff Welch", + "email": "whatthejeff@gmail.com" + }, { "name": "Adam Harvey", "email": "aharvey@php.net" @@ -1948,24 +2182,34 @@ ], "description": "Provides functionality to recursively process PHP variables", "homepage": "http://www.github.com/sebastianbergmann/recursion-context", - "time": "2017-03-03T06:23:57+00:00" + "support": { + "issues": "https://github.com/sebastianbergmann/recursion-context/issues", + "source": "https://github.com/sebastianbergmann/recursion-context/tree/3.0.1" + }, + "funding": [ + { + "url": "https://github.com/sebastianbergmann", + "type": "github" + } + ], + "time": "2020-11-30T07:34:24+00:00" }, { "name": "sebastian/resource-operations", - "version": "2.0.1", + "version": "2.0.2", "source": { "type": "git", "url": "https://github.com/sebastianbergmann/resource-operations.git", - "reference": "4d7a795d35b889bf80a0cc04e08d77cedfa917a9" + "reference": "31d35ca87926450c44eae7e2611d45a7a65ea8b3" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/sebastianbergmann/resource-operations/zipball/4d7a795d35b889bf80a0cc04e08d77cedfa917a9", - "reference": "4d7a795d35b889bf80a0cc04e08d77cedfa917a9", + "url": "https://api.github.com/repos/sebastianbergmann/resource-operations/zipball/31d35ca87926450c44eae7e2611d45a7a65ea8b3", + "reference": "31d35ca87926450c44eae7e2611d45a7a65ea8b3", "shasum": "" }, "require": { - "php": "^7.1" + "php": ">=7.1" }, "type": "library", "extra": { @@ -1990,7 +2234,73 @@ ], "description": "Provides a list of PHP built-in functions that operate on resources", "homepage": "https://www.github.com/sebastianbergmann/resource-operations", - "time": "2018-10-04T04:07:39+00:00" + "support": { + "issues": "https://github.com/sebastianbergmann/resource-operations/issues", + "source": "https://github.com/sebastianbergmann/resource-operations/tree/2.0.2" + }, + "funding": [ + { + "url": "https://github.com/sebastianbergmann", + "type": "github" + } + ], + "time": "2020-11-30T07:30:19+00:00" + }, + { + "name": "sebastian/type", + "version": "1.1.4", + "source": { + "type": "git", + "url": "https://github.com/sebastianbergmann/type.git", + "reference": "0150cfbc4495ed2df3872fb31b26781e4e077eb4" + }, + "dist": { + "type": "zip", + "url": "https://api.github.com/repos/sebastianbergmann/type/zipball/0150cfbc4495ed2df3872fb31b26781e4e077eb4", + "reference": "0150cfbc4495ed2df3872fb31b26781e4e077eb4", + "shasum": "" + }, + "require": { + "php": ">=7.2" + }, + "require-dev": { + "phpunit/phpunit": "^8.2" + }, + "type": "library", + "extra": { + "branch-alias": { + "dev-master": "1.1-dev" + } + }, + "autoload": { + "classmap": [ + "src/" + ] + }, + "notification-url": "https://packagist.org/downloads/", + "license": [ + "BSD-3-Clause" + ], + "authors": [ + { + "name": "Sebastian Bergmann", + "email": "sebastian@phpunit.de", + "role": "lead" + } + ], + "description": "Collection of value objects that represent the types of the PHP type system", + "homepage": "https://github.com/sebastianbergmann/type", + "support": { + "issues": "https://github.com/sebastianbergmann/type/issues", + "source": "https://github.com/sebastianbergmann/type/tree/1.1.4" + }, + "funding": [ + { + "url": "https://github.com/sebastianbergmann", + "type": "github" + } + ], + "time": "2020-11-30T07:25:11+00:00" }, { "name": "sebastian/version", @@ -2033,28 +2343,32 @@ ], "description": "Library that helps with managing the version number of Git-hosted PHP projects", "homepage": "https://github.com/sebastianbergmann/version", + "support": { + "issues": "https://github.com/sebastianbergmann/version/issues", + "source": "https://github.com/sebastianbergmann/version/tree/master" + }, "time": "2016-10-03T07:35:21+00:00" }, { "name": "sirbrillig/phpcs-variable-analysis", - "version": "v2.9.0", + "version": "v2.10.2", "source": { "type": "git", "url": "https://github.com/sirbrillig/phpcs-variable-analysis.git", - "reference": "ff54d4ec7f2bd152d526fdabfeff639aa9b8be01" + "reference": "0775e0c683badad52c03b11c2cd86a9fdecb937a" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/sirbrillig/phpcs-variable-analysis/zipball/ff54d4ec7f2bd152d526fdabfeff639aa9b8be01", - "reference": "ff54d4ec7f2bd152d526fdabfeff639aa9b8be01", + "url": "https://api.github.com/repos/sirbrillig/phpcs-variable-analysis/zipball/0775e0c683badad52c03b11c2cd86a9fdecb937a", + "reference": "0775e0c683badad52c03b11c2cd86a9fdecb937a", "shasum": "" }, "require": { "php": ">=5.4.0", - "squizlabs/php_codesniffer": "^3.1" + "squizlabs/php_codesniffer": "^3.5" }, "require-dev": { - "dealerdirect/phpcodesniffer-composer-installer": "^0.4.4 || ^0.5 || ^0.6", + "dealerdirect/phpcodesniffer-composer-installer": "^0.7.0", "limedeck/phpunit-detailed-printer": "^3.1 || ^4.0 || ^5.0", "phpstan/phpstan": "^0.11.8", "phpunit/phpunit": "^5.0 || ^6.5 || ^7.0 || ^8.0", @@ -2081,36 +2395,41 @@ } ], "description": "A PHPCS sniff to detect problems with variables.", - "time": "2020-10-07T23:32:29+00:00" + "support": { + "issues": "https://github.com/sirbrillig/phpcs-variable-analysis/issues", + "source": "https://github.com/sirbrillig/phpcs-variable-analysis", + "wiki": "https://github.com/sirbrillig/phpcs-variable-analysis/wiki" + }, + "time": "2021-01-08T16:31:05+00:00" }, { "name": "spatie/phpunit-watcher", - "version": "1.23.0", + "version": "1.23.1", "source": { "type": "git", "url": "https://github.com/spatie/phpunit-watcher.git", - "reference": "8a8e0c3c8f3f03dfdb6bf62abf89c1b7273fc0b3" + "reference": "0c70d569658a1cad9a6869716a4351d2ccfec4d1" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/spatie/phpunit-watcher/zipball/8a8e0c3c8f3f03dfdb6bf62abf89c1b7273fc0b3", - "reference": "8a8e0c3c8f3f03dfdb6bf62abf89c1b7273fc0b3", + "url": "https://api.github.com/repos/spatie/phpunit-watcher/zipball/0c70d569658a1cad9a6869716a4351d2ccfec4d1", + "reference": "0c70d569658a1cad9a6869716a4351d2ccfec4d1", "shasum": "" }, "require": { "clue/stdio-react": "^2.0", "jolicode/jolinotif": "^2.0", - "php": "^7.2", - "symfony/console": "^4.0|^5.0", - "symfony/process": "^4.0|^5.0", - "symfony/yaml": "^4.0|^5.0", + "php": "^7.2 | ^8.0", + "symfony/console": "^5.0", + "symfony/process": "^5.0", + "symfony/yaml": "^5.0", "yosymfony/resource-watcher": "^2.0" }, "conflict": { "yosymfony/resource-watcher": "<2.0" }, "require-dev": { - "phpunit/phpunit": "^8.0" + "phpunit/phpunit": "^8.0 | ^9.0" }, "bin": [ "phpunit-watcher" @@ -2139,7 +2458,11 @@ "phpunit-watcher", "spatie" ], - "time": "2020-10-27T07:36:25+00:00" + "support": { + "issues": "https://github.com/spatie/phpunit-watcher/issues", + "source": "https://github.com/spatie/phpunit-watcher/tree/1.23.1" + }, + "time": "2020-10-31T17:47:29+00:00" }, { "name": "squizlabs/php_codesniffer", @@ -2190,20 +2513,25 @@ "phpcs", "standards" ], + "support": { + "issues": "https://github.com/squizlabs/PHP_CodeSniffer/issues", + "source": "https://github.com/squizlabs/PHP_CodeSniffer", + "wiki": "https://github.com/squizlabs/PHP_CodeSniffer/wiki" + }, "time": "2020-10-23T02:01:07+00:00" }, { "name": "symfony/console", - "version": "v5.1.8", + "version": "v5.2.2", "source": { "type": "git", "url": "https://github.com/symfony/console.git", - "reference": "e0b2c29c0fa6a69089209bbe8fcff4df2a313d0e" + "reference": "d62ec79478b55036f65e2602e282822b8eaaff0a" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/symfony/console/zipball/e0b2c29c0fa6a69089209bbe8fcff4df2a313d0e", - "reference": "e0b2c29c0fa6a69089209bbe8fcff4df2a313d0e", + "url": "https://api.github.com/repos/symfony/console/zipball/d62ec79478b55036f65e2602e282822b8eaaff0a", + "reference": "d62ec79478b55036f65e2602e282822b8eaaff0a", "shasum": "" }, "require": { @@ -2262,8 +2590,17 @@ "homepage": "https://symfony.com/contributors" } ], - "description": "Symfony Console Component", + "description": "Eases the creation of beautiful and testable command line interfaces", "homepage": "https://symfony.com", + "keywords": [ + "cli", + "command line", + "console", + "terminal" + ], + "support": { + "source": "https://github.com/symfony/console/tree/v5.2.2" + }, "funding": [ { "url": "https://symfony.com/sponsor", @@ -2278,7 +2615,7 @@ "type": "tidelift" } ], - "time": "2020-10-24T12:01:57+00:00" + "time": "2021-01-27T10:15:41+00:00" }, { "name": "symfony/deprecation-contracts", @@ -2328,6 +2665,9 @@ ], "description": "A generic function and convention to trigger deprecation notices", "homepage": "https://symfony.com", + "support": { + "source": "https://github.com/symfony/deprecation-contracts/tree/master" + }, "funding": [ { "url": "https://symfony.com/sponsor", @@ -2346,16 +2686,16 @@ }, { "name": "symfony/finder", - "version": "v5.1.8", + "version": "v5.2.2", "source": { "type": "git", "url": "https://github.com/symfony/finder.git", - "reference": "e70eb5a69c2ff61ea135a13d2266e8914a67b3a0" + "reference": "196f45723b5e618bf0e23b97e96d11652696ea9e" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/symfony/finder/zipball/e70eb5a69c2ff61ea135a13d2266e8914a67b3a0", - "reference": "e70eb5a69c2ff61ea135a13d2266e8914a67b3a0", + "url": "https://api.github.com/repos/symfony/finder/zipball/196f45723b5e618bf0e23b97e96d11652696ea9e", + "reference": "196f45723b5e618bf0e23b97e96d11652696ea9e", "shasum": "" }, "require": { @@ -2384,8 +2724,11 @@ "homepage": "https://symfony.com/contributors" } ], - "description": "Symfony Finder Component", + "description": "Finds files and directories via an intuitive fluent interface", "homepage": "https://symfony.com", + "support": { + "source": "https://github.com/symfony/finder/tree/v5.2.2" + }, "funding": [ { "url": "https://symfony.com/sponsor", @@ -2400,20 +2743,20 @@ "type": "tidelift" } ], - "time": "2020-10-24T12:01:57+00:00" + "time": "2021-01-27T10:01:46+00:00" }, { "name": "symfony/polyfill-ctype", - "version": "v1.20.0", + "version": "v1.22.0", "source": { "type": "git", "url": "https://github.com/symfony/polyfill-ctype.git", - "reference": "f4ba089a5b6366e453971d3aad5fe8e897b37f41" + "reference": "c6c942b1ac76c82448322025e084cadc56048b4e" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/symfony/polyfill-ctype/zipball/f4ba089a5b6366e453971d3aad5fe8e897b37f41", - "reference": "f4ba089a5b6366e453971d3aad5fe8e897b37f41", + "url": "https://api.github.com/repos/symfony/polyfill-ctype/zipball/c6c942b1ac76c82448322025e084cadc56048b4e", + "reference": "c6c942b1ac76c82448322025e084cadc56048b4e", "shasum": "" }, "require": { @@ -2425,7 +2768,7 @@ "type": "library", "extra": { "branch-alias": { - "dev-main": "1.20-dev" + "dev-main": "1.22-dev" }, "thanks": { "name": "symfony/polyfill", @@ -2462,6 +2805,9 @@ "polyfill", "portable" ], + "support": { + "source": "https://github.com/symfony/polyfill-ctype/tree/v1.22.0" + }, "funding": [ { "url": "https://symfony.com/sponsor", @@ -2476,20 +2822,20 @@ "type": "tidelift" } ], - "time": "2020-10-23T14:02:19+00:00" + "time": "2021-01-07T16:49:33+00:00" }, { "name": "symfony/polyfill-intl-grapheme", - "version": "v1.20.0", + "version": "v1.22.0", "source": { "type": "git", "url": "https://github.com/symfony/polyfill-intl-grapheme.git", - "reference": "c7cf3f858ec7d70b89559d6e6eb1f7c2517d479c" + "reference": "267a9adeb8ecb8071040a740930e077cdfb987af" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/symfony/polyfill-intl-grapheme/zipball/c7cf3f858ec7d70b89559d6e6eb1f7c2517d479c", - "reference": "c7cf3f858ec7d70b89559d6e6eb1f7c2517d479c", + "url": "https://api.github.com/repos/symfony/polyfill-intl-grapheme/zipball/267a9adeb8ecb8071040a740930e077cdfb987af", + "reference": "267a9adeb8ecb8071040a740930e077cdfb987af", "shasum": "" }, "require": { @@ -2501,7 +2847,7 @@ "type": "library", "extra": { "branch-alias": { - "dev-main": "1.20-dev" + "dev-main": "1.22-dev" }, "thanks": { "name": "symfony/polyfill", @@ -2540,6 +2886,9 @@ "portable", "shim" ], + "support": { + "source": "https://github.com/symfony/polyfill-intl-grapheme/tree/v1.22.0" + }, "funding": [ { "url": "https://symfony.com/sponsor", @@ -2554,20 +2903,20 @@ "type": "tidelift" } ], - "time": "2020-10-23T14:02:19+00:00" + "time": "2021-01-07T16:49:33+00:00" }, { "name": "symfony/polyfill-intl-normalizer", - "version": "v1.20.0", + "version": "v1.22.0", "source": { "type": "git", "url": "https://github.com/symfony/polyfill-intl-normalizer.git", - "reference": "727d1096295d807c309fb01a851577302394c897" + "reference": "6e971c891537eb617a00bb07a43d182a6915faba" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/symfony/polyfill-intl-normalizer/zipball/727d1096295d807c309fb01a851577302394c897", - "reference": "727d1096295d807c309fb01a851577302394c897", + "url": "https://api.github.com/repos/symfony/polyfill-intl-normalizer/zipball/6e971c891537eb617a00bb07a43d182a6915faba", + "reference": "6e971c891537eb617a00bb07a43d182a6915faba", "shasum": "" }, "require": { @@ -2579,7 +2928,7 @@ "type": "library", "extra": { "branch-alias": { - "dev-main": "1.20-dev" + "dev-main": "1.22-dev" }, "thanks": { "name": "symfony/polyfill", @@ -2621,6 +2970,9 @@ "portable", "shim" ], + "support": { + "source": "https://github.com/symfony/polyfill-intl-normalizer/tree/v1.22.0" + }, "funding": [ { "url": "https://symfony.com/sponsor", @@ -2635,20 +2987,20 @@ "type": "tidelift" } ], - "time": "2020-10-23T14:02:19+00:00" + "time": "2021-01-07T17:09:11+00:00" }, { "name": "symfony/polyfill-mbstring", - "version": "v1.20.0", + "version": "v1.22.0", "source": { "type": "git", "url": "https://github.com/symfony/polyfill-mbstring.git", - "reference": "39d483bdf39be819deabf04ec872eb0b2410b531" + "reference": "f377a3dd1fde44d37b9831d68dc8dea3ffd28e13" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/symfony/polyfill-mbstring/zipball/39d483bdf39be819deabf04ec872eb0b2410b531", - "reference": "39d483bdf39be819deabf04ec872eb0b2410b531", + "url": "https://api.github.com/repos/symfony/polyfill-mbstring/zipball/f377a3dd1fde44d37b9831d68dc8dea3ffd28e13", + "reference": "f377a3dd1fde44d37b9831d68dc8dea3ffd28e13", "shasum": "" }, "require": { @@ -2660,7 +3012,7 @@ "type": "library", "extra": { "branch-alias": { - "dev-main": "1.20-dev" + "dev-main": "1.22-dev" }, "thanks": { "name": "symfony/polyfill", @@ -2698,6 +3050,9 @@ "portable", "shim" ], + "support": { + "source": "https://github.com/symfony/polyfill-mbstring/tree/v1.22.0" + }, "funding": [ { "url": "https://symfony.com/sponsor", @@ -2712,20 +3067,20 @@ "type": "tidelift" } ], - "time": "2020-10-23T14:02:19+00:00" + "time": "2021-01-07T16:49:33+00:00" }, { "name": "symfony/polyfill-php73", - "version": "v1.20.0", + "version": "v1.22.0", "source": { "type": "git", "url": "https://github.com/symfony/polyfill-php73.git", - "reference": "8ff431c517be11c78c48a39a66d37431e26a6bed" + "reference": "a678b42e92f86eca04b7fa4c0f6f19d097fb69e2" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/symfony/polyfill-php73/zipball/8ff431c517be11c78c48a39a66d37431e26a6bed", - "reference": "8ff431c517be11c78c48a39a66d37431e26a6bed", + "url": "https://api.github.com/repos/symfony/polyfill-php73/zipball/a678b42e92f86eca04b7fa4c0f6f19d097fb69e2", + "reference": "a678b42e92f86eca04b7fa4c0f6f19d097fb69e2", "shasum": "" }, "require": { @@ -2734,7 +3089,7 @@ "type": "library", "extra": { "branch-alias": { - "dev-main": "1.20-dev" + "dev-main": "1.22-dev" }, "thanks": { "name": "symfony/polyfill", @@ -2774,6 +3129,9 @@ "portable", "shim" ], + "support": { + "source": "https://github.com/symfony/polyfill-php73/tree/v1.22.0" + }, "funding": [ { "url": "https://symfony.com/sponsor", @@ -2788,20 +3146,20 @@ "type": "tidelift" } ], - "time": "2020-10-23T14:02:19+00:00" + "time": "2021-01-07T16:49:33+00:00" }, { "name": "symfony/polyfill-php80", - "version": "v1.20.0", + "version": "v1.22.0", "source": { "type": "git", "url": "https://github.com/symfony/polyfill-php80.git", - "reference": "e70aa8b064c5b72d3df2abd5ab1e90464ad009de" + "reference": "dc3063ba22c2a1fd2f45ed856374d79114998f91" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/symfony/polyfill-php80/zipball/e70aa8b064c5b72d3df2abd5ab1e90464ad009de", - "reference": "e70aa8b064c5b72d3df2abd5ab1e90464ad009de", + "url": "https://api.github.com/repos/symfony/polyfill-php80/zipball/dc3063ba22c2a1fd2f45ed856374d79114998f91", + "reference": "dc3063ba22c2a1fd2f45ed856374d79114998f91", "shasum": "" }, "require": { @@ -2810,7 +3168,7 @@ "type": "library", "extra": { "branch-alias": { - "dev-main": "1.20-dev" + "dev-main": "1.22-dev" }, "thanks": { "name": "symfony/polyfill", @@ -2854,6 +3212,9 @@ "portable", "shim" ], + "support": { + "source": "https://github.com/symfony/polyfill-php80/tree/v1.22.0" + }, "funding": [ { "url": "https://symfony.com/sponsor", @@ -2868,20 +3229,20 @@ "type": "tidelift" } ], - "time": "2020-10-23T14:02:19+00:00" + "time": "2021-01-07T16:49:33+00:00" }, { "name": "symfony/process", - "version": "v5.1.8", + "version": "v5.2.2", "source": { "type": "git", "url": "https://github.com/symfony/process.git", - "reference": "f00872c3f6804150d6a0f73b4151daab96248101" + "reference": "313a38f09c77fbcdc1d223e57d368cea76a2fd2f" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/symfony/process/zipball/f00872c3f6804150d6a0f73b4151daab96248101", - "reference": "f00872c3f6804150d6a0f73b4151daab96248101", + "url": "https://api.github.com/repos/symfony/process/zipball/313a38f09c77fbcdc1d223e57d368cea76a2fd2f", + "reference": "313a38f09c77fbcdc1d223e57d368cea76a2fd2f", "shasum": "" }, "require": { @@ -2911,8 +3272,11 @@ "homepage": "https://symfony.com/contributors" } ], - "description": "Symfony Process Component", + "description": "Executes commands in sub-processes", "homepage": "https://symfony.com", + "support": { + "source": "https://github.com/symfony/process/tree/v5.2.2" + }, "funding": [ { "url": "https://symfony.com/sponsor", @@ -2927,7 +3291,7 @@ "type": "tidelift" } ], - "time": "2020-10-24T12:01:57+00:00" + "time": "2021-01-27T10:15:41+00:00" }, { "name": "symfony/service-contracts", @@ -2989,6 +3353,9 @@ "interoperability", "standards" ], + "support": { + "source": "https://github.com/symfony/service-contracts/tree/master" + }, "funding": [ { "url": "https://symfony.com/sponsor", @@ -3007,16 +3374,16 @@ }, { "name": "symfony/string", - "version": "v5.1.8", + "version": "v5.2.2", "source": { "type": "git", "url": "https://github.com/symfony/string.git", - "reference": "a97573e960303db71be0dd8fda9be3bca5e0feea" + "reference": "c95468897f408dd0aca2ff582074423dd0455122" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/symfony/string/zipball/a97573e960303db71be0dd8fda9be3bca5e0feea", - "reference": "a97573e960303db71be0dd8fda9be3bca5e0feea", + "url": "https://api.github.com/repos/symfony/string/zipball/c95468897f408dd0aca2ff582074423dd0455122", + "reference": "c95468897f408dd0aca2ff582074423dd0455122", "shasum": "" }, "require": { @@ -3059,7 +3426,7 @@ "homepage": "https://symfony.com/contributors" } ], - "description": "Symfony String component", + "description": "Provides an object-oriented API to strings and deals with bytes, UTF-8 code points and grapheme clusters in a unified way", "homepage": "https://symfony.com", "keywords": [ "grapheme", @@ -3069,6 +3436,9 @@ "utf-8", "utf8" ], + "support": { + "source": "https://github.com/symfony/string/tree/v5.2.2" + }, "funding": [ { "url": "https://symfony.com/sponsor", @@ -3083,20 +3453,20 @@ "type": "tidelift" } ], - "time": "2020-10-24T12:01:57+00:00" + "time": "2021-01-25T15:14:59+00:00" }, { "name": "symfony/yaml", - "version": "v5.1.8", + "version": "v5.2.2", "source": { "type": "git", "url": "https://github.com/symfony/yaml.git", - "reference": "f284e032c3cefefb9943792132251b79a6127ca6" + "reference": "6bb8b36c6dea8100268512bf46e858c8eb5c545e" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/symfony/yaml/zipball/f284e032c3cefefb9943792132251b79a6127ca6", - "reference": "f284e032c3cefefb9943792132251b79a6127ca6", + "url": "https://api.github.com/repos/symfony/yaml/zipball/6bb8b36c6dea8100268512bf46e858c8eb5c545e", + "reference": "6bb8b36c6dea8100268512bf46e858c8eb5c545e", "shasum": "" }, "require": { @@ -3139,8 +3509,11 @@ "homepage": "https://symfony.com/contributors" } ], - "description": "Symfony Yaml Component", + "description": "Loads and dumps YAML files", "homepage": "https://symfony.com", + "support": { + "source": "https://github.com/symfony/yaml/tree/v5.2.2" + }, "funding": [ { "url": "https://symfony.com/sponsor", @@ -3155,7 +3528,7 @@ "type": "tidelift" } ], - "time": "2020-10-24T12:03:25+00:00" + "time": "2021-01-27T10:01:46+00:00" }, { "name": "theseer/tokenizer", @@ -3195,6 +3568,10 @@ } ], "description": "A small library for converting tokenized PHP source code into XML and potentially other formats", + "support": { + "issues": "https://github.com/theseer/tokenizer/issues", + "source": "https://github.com/theseer/tokenizer/tree/master" + }, "funding": [ { "url": "https://github.com/theseer", @@ -3208,12 +3585,12 @@ "version": "1.9.1", "source": { "type": "git", - "url": "https://github.com/webmozart/assert.git", + "url": "https://github.com/webmozarts/assert.git", "reference": "bafc69caeb4d49c39fd0779086c03a3738cbb389" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/webmozart/assert/zipball/bafc69caeb4d49c39fd0779086c03a3738cbb389", + "url": "https://api.github.com/repos/webmozarts/assert/zipball/bafc69caeb4d49c39fd0779086c03a3738cbb389", "reference": "bafc69caeb4d49c39fd0779086c03a3738cbb389", "shasum": "" }, @@ -3250,6 +3627,10 @@ "check", "validate" ], + "support": { + "issues": "https://github.com/webmozarts/assert/issues", + "source": "https://github.com/webmozarts/assert/tree/1.9.1" + }, "time": "2020-07-08T17:02:28+00:00" }, { @@ -3296,20 +3677,25 @@ "standards", "wordpress" ], + "support": { + "issues": "https://github.com/WordPress/WordPress-Coding-Standards/issues", + "source": "https://github.com/WordPress/WordPress-Coding-Standards", + "wiki": "https://github.com/WordPress/WordPress-Coding-Standards/wiki" + }, "time": "2020-05-13T23:57:56+00:00" }, { "name": "wp-phpunit/wp-phpunit", - "version": "5.5.3", + "version": "5.6.0", "source": { "type": "git", "url": "https://github.com/wp-phpunit/wp-phpunit.git", - "reference": "763121e752594664c150643e05c991a0acf3800a" + "reference": "7130a214573cc8c12a0f8fe8a74b18b453bce1e9" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/wp-phpunit/wp-phpunit/zipball/763121e752594664c150643e05c991a0acf3800a", - "reference": "763121e752594664c150643e05c991a0acf3800a", + "url": "https://api.github.com/repos/wp-phpunit/wp-phpunit/zipball/7130a214573cc8c12a0f8fe8a74b18b453bce1e9", + "reference": "7130a214573cc8c12a0f8fe8a74b18b453bce1e9", "shasum": "" }, "type": "library", @@ -3339,7 +3725,12 @@ "test", "wordpress" ], - "time": "2020-09-02T15:53:50+00:00" + "support": { + "docs": "https://github.com/wp-phpunit/docs", + "issues": "https://github.com/wp-phpunit/issues", + "source": "https://github.com/wp-phpunit/wp-phpunit" + }, + "time": "2020-12-09T18:06:02+00:00" }, { "name": "yosymfony/resource-watcher", @@ -3392,6 +3783,10 @@ "symfony", "watcher" ], + "support": { + "issues": "https://github.com/yosymfony/resource-watcher/issues", + "source": "https://github.com/yosymfony/resource-watcher/tree/master" + }, "time": "2020-01-04T15:36:55+00:00" } ], @@ -3402,5 +3797,5 @@ "prefer-lowest": false, "platform": [], "platform-dev": [], - "plugin-api-version": "1.1.0" + "plugin-api-version": "2.0.0" } diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000000000..26cdbe393ad49e --- /dev/null +++ b/docs/README.md @@ -0,0 +1,42 @@ +# Getting started + +**Gutenberg** is a codename for a whole new paradigm in WordPress site building and publishing, that aims to revolutionize the entire publishing experience as much as Gutenberg did the printed word. The project is right now in the second phase of a four-phase process that will touch every piece of WordPress -- Editing, **Customization** (which includes Full Site Editing, Block Patterns, Block Directory and Block based themes), Collaboration, and Multilingual -- and is focused on a new editing experience, the block editor (which is the topic of the current documentation). + +![Quick view of the block editor](https://raw.githubusercontent.com/WordPress/gutenberg/trunk/docs/assets/quick-view-of-the-block-editor.png) + +**Legend :** + +1. Block Inserter +2. Block editor content area +3. Settings Sidebar + +Using a system of Blocks to compose and format content, the new block-based editor is designed to create rich, flexible layouts for websites and digital products. Content is created in the unit of blocks instead of freeform text with inserted media, embeds and Shortcodes (there's a Shortcode block though). + +Blocks treat Paragraphs, Headings, Media, and Embeds all as components that, when strung together, make up the content stored in the WordPress database, replacing the traditional concept of freeform text with embedded media and shortcodes. The new editor is designed with progressive enhancement, meaning that it is back-compatible with all legacy content, and it also offers a process to try to convert and split a Classic block into equivalent blocks using client-side parsing. Finally, the blocks offer enhanced editing and format controls. + +The Editor offers rich new value to users with visual, drag-and-drop creation tools and powerful developer enhancements with modern vendor packages, reusable components, rich APIs and hooks to modify and extend the editor through Custom Blocks, Custom Block Styles and Plugins. + +[Learn to use the block editor](https://wordpress.org/support/article/wordpress-editor/) to create media-rich posts and pages. + +## Quick links + +### Create a Block Tutorial + +[Learn how to create your first block](/docs/getting-started/tutorials/create-block/README.md) for the WordPress block editor. From setting up your development environment, tools, and getting comfortable with the new development model, this tutorial covers all what you need to know to get started with the block editor. + +### Develop for the block editor + +Whether you want to extend the functionality of the block editor, or create a plugin based on it, [see the developer documentation](/docs/how-to-guides/README.md) to find all the information about the basic concepts you need to get started, the block editor APIs and its architecture. + +- [Gutenberg Architecture](/docs/explanations/architecture/README.md) +- [Block Style Variations](/docs/reference-guides/filters/block-filters.md#block-style-variations) +- [Creating Block Patterns](/docs/reference-guides/block-api/block-patterns.md) +- [Theming for the Block Editor](/docs/how-to-guides/themes/README.md) +- [Block API Reference](/docs/reference-guides/block-api/README.md) +- [Block Editor Accessibility](/docs/reference-guides/accessibility.md) +- [Internationalization](/docs/how-to-guides/internationalization.md) + +### Contribute to the block editor + +Everything you need to know to [start contributing to the block editor](/docs/contributors/README.md) . Whether you are interested in the design, code, triage, documentation, support or internationalization of the block editor, you will find here guides to help you. + diff --git a/docs/architecture/automated-testing.md b/docs/architecture/automated-testing.md deleted file mode 100644 index f7cee72b7cd7ed..00000000000000 --- a/docs/architecture/automated-testing.md +++ /dev/null @@ -1,20 +0,0 @@ -# Automated Testing - -## Why is Puppeteer the tool of choice for end-to-end tests? - -There exists a rich ecosystem of tooling available for web-based end-to-end automated testing. Thus, it's a common question: "Why does Gutenberg use [Puppeteer](https://developers.google.com/web/tools/puppeteer/) instead of ([Cypress](https://cypress.io/), [Selenium](https://www.selenium.dev/), [Playwright](https://github.com/microsoft/playwright), etc)?". Given some historical unreliability of the build results associated with end-to-end tests, it's especially natural to weigh this question in considering whether our tools are providing more value than the effort required in maintaining them. While we should always be comfortable in reevaluating earlier decisions, there were and continue to be many reasons that Puppeteer is the best compromise of the options available for end-to-end testing. - -These include: - -- **Interoperability with existing testing framework**. Puppeteer is "just" a tool for controlling a Chrome browser, and makes no assumptions about how it's integrated into a testing environment. While this requires some additional effort in ensuring the test environment is available, it also allows for cohesion in how it integrates with an existing setup. Gutenberg is able to consistently use Jest for both unit testing and end-to-end testing. This is contrasted with other solutions like Cypress, which provide their own testing framework and assertion library as part of an all-in-one solution. -- **An expressive but predictable API**. Puppeteer strikes a nice balance between low-level access to browser behavior, while retaining an expressive API for issuing and awaiting responses to those commands using modern JavaScript [`async` and `await` syntax](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Asynchronous/Async_await). This is contrasted with other solutions, which either don't support or leverage native language async functionality, don't expose direct access to the browser, or leverage custom domain-specific language syntaxes for expressing browser commands and assertions. The fact that Puppeteer largely targets the Chrome browser is non-ideal in how it does not provide full browser coverage. On the other hand, the limited set of browser targets offers more consistent results and stronger guarantees about how code is evaluated in the browser environment. -- **Surfacing bugs, not obscuring them**. Many alternative solutions offer options to automatically await settled network requests or asynchronous appearance of elements on the page. While this can serve as a convenience in accounting for unpredictable delays, it can also unknowingly cause oversight of legitimate user-facing issues. For example, if an element will only appear on the page after some network request or computation has completed, it may be easy to overlook that these delays can cause unpredictable and frustrating behavior for users ([example](https://github.com/WordPress/gutenberg/pull/11287)). Given that developers often test on high-end hardware and stable network connections, consideration of resiliency on low-end hardware or spotty network availability is not always on the forefront of one's considerations. Puppeteer forces us to acknowledge these delays with explicit `waitFor*` expressions, putting us in much greater alignment with the real-world experience of an end-user. -- **Debugging**. It's important that in that case that a test fails, there should be straight-forward means to diagnose and resolve the issue. While its offerings are rather simplistic relative to the competition, Puppeteer does expose options to run tests as "headful" (with the browser visible) and with delayed actions. Combined with the fact that it interoperates well with native language / runtime features (e.g. debugger statements or breakpoints), this provides developers with sufficient debugging access. - -For more context, refer to the following resources: - -- [Testing Overview: End-to-End Testing](https://github.com/WordPress/gutenberg/blob/master/docs/contributors/testing-overview.md#end-to-end-testing) -- [Testing: Experiment with Puppeteer for E2E testing](https://github.com/WordPress/gutenberg/pull/5618) - - In early iterations, the contributing team opted to use Cypress for end-to-end testing. This pull request outlines problems with the approach, and proposed the initial transition to Puppeteer. -- [JavaScript Chat Summary: January 28, 2020](https://make.wordpress.org/core/2020/02/04/javascript-chat-summary-january-28-2020/) - - Playwright is a new offering created by many of the original contributors to Puppeteer. It offers increased browser coverage and improved reliability of tests. While still early in development at the time of this writing, there has been some interest in evaluating it for future use as an end-to-end testing solution. diff --git a/docs/architecture/key-concepts.md b/docs/architecture/key-concepts.md deleted file mode 100644 index 0da44d6d553c9e..00000000000000 --- a/docs/architecture/key-concepts.md +++ /dev/null @@ -1,62 +0,0 @@ -# Key Concepts - -## Blocks - -Blocks are an abstract unit for organizing and composing content, strung together to create content for a webpage. - -Blocks are hierarchical in that a block can be a child of or parent to another block. For example, a two-column Columns block can be the parent block to multiple child blocks in each of its columns. - -If it helps, you can think of blocks as a more graceful shortcode, with rich formatting tools for users to compose content. To this point, there is a new Block Grammar. Distilled, the block grammar is an HTML comment, either a self-closing tag or with a beginning tag and ending tag. In the main tag, depending on the block type and user customizations, there can be a JSON object. This raw form of the block is referred to as serialized. - -```html - -

Welcome to the world of blocks.

- -``` - -Blocks can be static or dynamic. Static blocks contain rendered content and an object of Attributes used to re-render based on changes. Dynamic blocks require server-side data and rendering while the post content is being generated (rendering). - -Each block contains Attributes or configuration settings, which can be sourced from raw HTML in the content via meta or other customizable origins. - -The Paragraph is the default block. Instead of a new line upon typing `return` on a keyboard, try to think of it as an empty Paragraph block (type "/" to trigger an autocompleting Slash Inserter -- "/image" will pull up Images as well as Instagram embeds). - -Users insert new blocks by clicking the plus button for the Block Inserter, typing "/" for the Slash Inserter, or typing `return` for a blank Paragraph block. - -Blocks can be duplicated within content using the menu from the block's toolbar or via keyboard shortcut. - -Blocks can also be made repeatable, allowing them to be shared across posts and post types and/or used multiple times in the same post. If a reusable block is edited in one place, those changes are reflected everywhere that that block is used. - -Blocks can be limited or locked-in-place by Templates and custom code. - -#### More on Blocks - -- **Block API** -- **Block Styles** -- **Tutorial: Building A Custom Block** - -## Block Categories - -In the Block Inserter (the accordion-sorted, popup modal that shows a site's available blocks to users) each accordion title is a Block Category, which are either the defaults or customized by developers through Plugins or code. - -## Reusable blocks - -Reusable blocks is a block (or multiple blocks) that you can insert, modify, repeatable piece of content. - -The content and style of a reusable block is intended to be consistent wherever it is used. - -Examples of reusable blocks include a block consisting of a heading whose content and a custom color that would be appear on multiple pages of the site and sidebar widgets that would appear on every page (widgets are planned to be available, but not yet possible, in Gutenberg). - -Any edits to a reusable block will appear on every other use of that block, saving time from having to make the same edit on different posts. - -Reusable blocks are stored as a hidden post type (wp_block) and are dynamic blocks that "ref" or reference the post_id and return the post_content for that block. - -The same reusable block can be used across different post types (e.g. post and page). - -If you need to create a structure (a block consisting of heading, paragraph, and list) that is very similar across multiple posts but the content is slightly different across those pages or posts, you can do the following to minimize the amount of duplicate work to do: - -1. create a 'skeleton' that will have shared characteristics (e.g. the same color background, font size) -1. save this as a reusable block. -1. Then, on other pages/posts: -1. Within the block editor: insert the reusable block -1. Open the block's properties (three dots) -and "convert to regular block"; the block is no longer 'reusable' and all edits to this block will only appear on this page/post. diff --git a/docs/architecture/readme.md b/docs/architecture/readme.md deleted file mode 100644 index c0b214d6147fed..00000000000000 --- a/docs/architecture/readme.md +++ /dev/null @@ -1,13 +0,0 @@ -# Architecture - -Let’s look at the big picture and the architectural and UX principles of the block editor and the Gutenberg repository. - -- [Key Concepts](/docs/architecture/key-concepts.md) -- [Data Format And Data Flow](/docs/architecture/data-flow.md) -- [Understand the repository folder structure](/docs/architecture/folder-structure.md). -- [Modularity and WordPress Packages](/docs/architecture/modularity.md). -- [Block Editor Performance](/docs/architecture/performance.md). -- What are the decision decisions behind the Data Module? -- [Why is Puppeteer the tool of choice for end-to-end tests?](/docs/architecture/automated-testing.md) -- [What's the difference between the different editor packages? What's the purpose of each package?](/docs/architecture/modularity.md#whats-the-difference-between-the-different-editor-packages-whats-the-purpose-of-each-package) -- [Template and template parts flows](/docs/architecture/fse-templates.md) diff --git a/docs/designers-developers/assets/fancy-quote-in-inspector.png b/docs/assets/fancy-quote-in-inspector.png similarity index 100% rename from docs/designers-developers/assets/fancy-quote-in-inspector.png rename to docs/assets/fancy-quote-in-inspector.png diff --git a/docs/designers-developers/assets/fancy-quote-with-style.png b/docs/assets/fancy-quote-with-style.png similarity index 100% rename from docs/designers-developers/assets/fancy-quote-with-style.png rename to docs/assets/fancy-quote-with-style.png diff --git a/docs/designers-developers/assets/inspector.png b/docs/assets/inspector.png similarity index 100% rename from docs/designers-developers/assets/inspector.png rename to docs/assets/inspector.png diff --git a/docs/designers-developers/assets/js-tutorial-console-log-error.png b/docs/assets/js-tutorial-console-log-error.png similarity index 100% rename from docs/designers-developers/assets/js-tutorial-console-log-error.png rename to docs/assets/js-tutorial-console-log-error.png diff --git a/docs/designers-developers/assets/js-tutorial-console-log-success.png b/docs/assets/js-tutorial-console-log-success.png similarity index 100% rename from docs/designers-developers/assets/js-tutorial-console-log-success.png rename to docs/assets/js-tutorial-console-log-success.png diff --git a/docs/designers-developers/assets/js-tutorial-error-blocks-undefined.png b/docs/assets/js-tutorial-error-blocks-undefined.png similarity index 100% rename from docs/designers-developers/assets/js-tutorial-error-blocks-undefined.png rename to docs/assets/js-tutorial-error-blocks-undefined.png diff --git a/docs/designers-developers/assets/plugin-block-settings-menu-item-screenshot.png b/docs/assets/plugin-block-settings-menu-item-screenshot.png similarity index 100% rename from docs/designers-developers/assets/plugin-block-settings-menu-item-screenshot.png rename to docs/assets/plugin-block-settings-menu-item-screenshot.png diff --git a/docs/designers-developers/assets/plugin-more-menu-item.png b/docs/assets/plugin-more-menu-item.png similarity index 100% rename from docs/designers-developers/assets/plugin-more-menu-item.png rename to docs/assets/plugin-more-menu-item.png diff --git a/docs/designers-developers/assets/plugin-post-publish-panel.png b/docs/assets/plugin-post-publish-panel.png similarity index 100% rename from docs/designers-developers/assets/plugin-post-publish-panel.png rename to docs/assets/plugin-post-publish-panel.png diff --git a/docs/designers-developers/assets/plugin-post-status-info-location.png b/docs/assets/plugin-post-status-info-location.png similarity index 100% rename from docs/designers-developers/assets/plugin-post-status-info-location.png rename to docs/assets/plugin-post-status-info-location.png diff --git a/docs/designers-developers/assets/plugin-pre-publish-panel.png b/docs/assets/plugin-pre-publish-panel.png similarity index 100% rename from docs/designers-developers/assets/plugin-pre-publish-panel.png rename to docs/assets/plugin-pre-publish-panel.png diff --git a/docs/designers-developers/assets/plugin-sidebar-closed-state.png b/docs/assets/plugin-sidebar-closed-state.png similarity index 100% rename from docs/designers-developers/assets/plugin-sidebar-closed-state.png rename to docs/assets/plugin-sidebar-closed-state.png diff --git a/docs/designers-developers/assets/plugin-sidebar-more-menu-item.gif b/docs/assets/plugin-sidebar-more-menu-item.gif similarity index 100% rename from docs/designers-developers/assets/plugin-sidebar-more-menu-item.gif rename to docs/assets/plugin-sidebar-more-menu-item.gif diff --git a/docs/designers-developers/assets/plugin-sidebar-open-state.png b/docs/assets/plugin-sidebar-open-state.png similarity index 100% rename from docs/designers-developers/assets/plugin-sidebar-open-state.png rename to docs/assets/plugin-sidebar-open-state.png diff --git a/docs/assets/quick-view-of-the-block-editor.png b/docs/assets/quick-view-of-the-block-editor.png new file mode 100644 index 00000000000000..1bab7e8cb36b4c Binary files /dev/null and b/docs/assets/quick-view-of-the-block-editor.png differ diff --git a/docs/designers-developers/assets/sidebar-style-and-controls.png b/docs/assets/sidebar-style-and-controls.png similarity index 100% rename from docs/designers-developers/assets/sidebar-style-and-controls.png rename to docs/assets/sidebar-style-and-controls.png diff --git a/docs/designers-developers/assets/sidebar-up-and-running.png b/docs/assets/sidebar-up-and-running.png similarity index 100% rename from docs/designers-developers/assets/sidebar-up-and-running.png rename to docs/assets/sidebar-up-and-running.png diff --git a/docs/designers-developers/assets/toolbar-text.png b/docs/assets/toolbar-text.png similarity index 100% rename from docs/designers-developers/assets/toolbar-text.png rename to docs/assets/toolbar-text.png diff --git a/docs/designers-developers/assets/toolbar-with-custom-button.png b/docs/assets/toolbar-with-custom-button.png similarity index 100% rename from docs/designers-developers/assets/toolbar-with-custom-button.png rename to docs/assets/toolbar-with-custom-button.png diff --git a/docs/contributors/readme.md b/docs/contributors/README.md similarity index 84% rename from docs/contributors/readme.md rename to docs/contributors/README.md index e51702b7248424..08b0d3ca0dc421 100644 --- a/docs/contributors/readme.md +++ b/docs/contributors/README.md @@ -8,11 +8,11 @@ Gutenberg is a sub-project of Core WordPress. Please see the [Core Contributor H Find the section below based on what you are looking to contribute: -- **Code?** See the [developer section](/docs/contributors/develop.md). +- **Code?** See the [developer section](/docs/contributors/code/README.md). -- **Design?** See the [design section](/docs/contributors/design.md). +- **Design?** See the [design section](/docs/contributors/design/README.md). -- **Documentation?** See the [documentation section](/docs/contributors/document.md) +- **Documentation?** See the [documentation section](/docs/contributors/documentation/README.md) - **Triage Support?** See the [triaging issues section](/docs/contributors/triage.md) @@ -30,4 +30,4 @@ The Gutenberg project uses Github for managing code and tracking issues. Please ## Guidelines -See the [Contributing Guidelines](https://github.com/WordPress/gutenberg/blob/master/CONTRIBUTING.md) for the rules around contributing: This includes the code of conduct and licensing information. +See the [Contributing Guidelines](https://github.com/WordPress/gutenberg/blob/HEAD/CONTRIBUTING.md) for the rules around contributing: This includes the code of conduct and licensing information. diff --git a/docs/contributors/accessibility-testing.md b/docs/contributors/accessibility-testing.md new file mode 100644 index 00000000000000..4e6e915222e80d --- /dev/null +++ b/docs/contributors/accessibility-testing.md @@ -0,0 +1,65 @@ +# Accessibility Testing + +This is a guide on how to test accessibility on Gutenberg. This is a living document that can be improved over time with new approaches and techniques. + +## Getting Started + +Make sure you have set up your local environment following the instructions on [Getting Started](/docs/contributors/code/getting-started-with-code-contribution.md). + +## Keyboard Testing + +In addition to mouse, make sure the interface is fully accessible for keyboard-only users. Try to interact with your changes using only the keyboard: + +- Make sure interactive elements can receive focus using Tab, Shift+Tab or arrow keys. +- Buttons should be activable by pressing Enter and Space. +- Radio buttons and checkboxes should be checked by pressing Space, but not Enter. + +If the elements can be focused using arrow keys, but not Tab or Shift+Tab, consider grouping them using one of the [WAI-ARIA composite subclass roles](https://www.w3.org/TR/wai-aria-1.1/#composite), such as [`toolbar`](https://www.w3.org/TR/wai-aria-1.1/#toolbar), [`menu`](https://www.w3.org/TR/wai-aria-1.1/#menu) and [`listbox`](https://www.w3.org/TR/wai-aria-1.1/#listbox). + +If the interaction is complex or confusing to you, consider that it's also going to impact keyboard-only users. + +## Screen Reader Testing + +According to the [WebAIM: Screen Reader User Survey #8 Results](https://webaim.org/projects/screenreadersurvey8/#usage), these are the most common screen reader and browser combinations: + +| Screen Reader & Browser | # of Respondents | % of Respondents | +|-----------------------------|------------------|------------------| +| JAWS with Chrome | 259 | 21.4% | +| NVDA with Firefox | 237 | 19.6% | +| NVDA with Chrome | 218 | 18.0% | +| JAWS with Internet Explorer | 139 | 11.5% | +| VoiceOver with Safari | 110 | 9.1% | +| JAWS with Firefox | 71 | 5.9% | +| VoiceOver with Chrome | 36 | 3.0% | +| NVDA with Internet Explorer | 14 | 1.2% | +| Other combinations | 126 | 10.4% | + +When testing with screen readers, try to use some of the combinations at the top of this list. For example, when testing with VoiceOver, it's preferrable to use Safari. + +### NVDA with Firefox + +[NVDA](https://www.nvaccess.org/about-nvda/) is a free screen reader for Windows and [the most popular one](https://webaim.org/projects/screenreadersurvey8/#primary). + +After installing it, you can activate NVDA by opening the app as you would do with other programs. An icon will appear on the System Tray where you have access to more options. It's recommended to enable the "Speech viewer" dialog so it's easier to demonstrate what's being announced by NVDA when you take screenshots. + +NVDA options with Speech viewer enabled + +While in the Gutenberg editor, with NVDA activated, you can press Insert+F7 to open the Elements List where you can find elements grouped by their types, such as links, headings, form fields, buttons and landmarks. + +NVDA Elements List dialog + +Make sure the elements have proper labels and prefer to navigate through landmarks and then use Tab and arrow keys to move through the elements within the landmarks. + +### VoiceOver with Safari + +[VoiceOver](https://support.apple.com/guide/voiceover-guide/welcome/web) is the native screen reader on macOS. You can enable it on System Preferences > Accessibility > VoiceOver > Enable VoiceOver or by quickly pressing Touch ID three times while holding the Command key. + +macOS accessibility preferences panel + +While in the Gutenberg editor, with VoiceOver activated, you can press Control+Option+U to open the Rotor and find more easily the different regions and elements on the page. This is also a good way to make sure elements are labelled correctly. If a name on this list doesn't make sense, it should be improved. + +Navigating through form controls and landmarks using the VoiceOver Rotor + +Prefer to select a region or another larger area to begin with instead of individual elements on the Rotor so you can better test the navigation within that region. + +Once you find the region you want to interact with, you can use Control+Option plus right or left arrow keys to move to the next or previous elements on the page. Then, follow the instructions that VoiceOver will announce. diff --git a/docs/contributors/develop.md b/docs/contributors/code/README.md similarity index 53% rename from docs/contributors/develop.md rename to docs/contributors/code/README.md index 01c015b37fc239..53637b380ca65d 100644 --- a/docs/contributors/develop.md +++ b/docs/contributors/code/README.md @@ -16,10 +16,11 @@ Browse [the issues list](https://github.com/wordpress/gutenberg/issues) to find ## Contributor Resources -* [Getting Started](/docs/contributors/getting-started.md) documents getting your development environment setup, this includes your test site and developer tools suggestions. -* [Git Workflow](/docs/contributors/git-workflow.md) documents the git process for deploying changes using pull requests. -* [Coding Guidelines](/docs/contributors/coding-guidelines.md) outline additional patterns and conventions used in the Gutenberg project. -* [Testing Overview](/docs/contributors/testing-overview.md) for PHP and JavaScript development in Gutenberg. -* [Managing Packages](/docs/contributors/managing-packages.md) documents the process for managing the npm packages. -* [Gutenberg Release Process](/docs/contributors/release.md) - a checklist for the different types of releases for the Gutenberg project. -* [React Native mobile Gutenberg](/docs/contributors/native-mobile.md) - a guide on the React Native based mobile Gutenberg editor. +* [Getting Started](/docs/contributors/code/getting-started-with-code-contribution.md) documents getting your development environment setup, this includes your test site and developer tools suggestions. +* [Git Workflow](/docs/contributors/code/git-workflow.md) documents the git process for deploying changes using pull requests. +* [Coding Guidelines](/docs/contributors/code/coding-guidelines.md) outline additional patterns and conventions used in the Gutenberg project. +* [Testing Overview](/docs/contributors/code/testing-overview.md) for PHP and JavaScript development in Gutenberg. +* [Accessibility Testing](/docs/contributors/accessibility-testing.md) documents the process of testing accessibility in Gutenberg. +* [Managing Packages](/docs/contributors/code/managing-packages.md) documents the process for managing the npm packages. +* [Gutenberg Release Process](/docs/contributors/code/release.md) - a checklist for the different types of releases for the Gutenberg project. +* [React Native mobile Gutenberg](/docs/contributors/code/native-mobile.md) - a guide on the React Native based mobile Gutenberg editor. diff --git a/docs/contributors/coding-guidelines.md b/docs/contributors/code/coding-guidelines.md similarity index 94% rename from docs/contributors/coding-guidelines.md rename to docs/contributors/code/coding-guidelines.md index 19e7702cfbad98..23f16e0f740c5d 100644 --- a/docs/contributors/coding-guidelines.md +++ b/docs/contributors/code/coding-guidelines.md @@ -53,7 +53,7 @@ export default function Notice( { children, onRemove, isDismissible } ) { } ``` -A component's class name should **never** be used outside its own folder (with rare exceptions such as [`_z-index.scss`](https://github.com/WordPress/gutenberg/blob/master/packages/base-styles/_z-index.scss)). If you need to inherit styles of another component in your own components, you should render an instance of that other component. At worst, you should duplicate the styles within your own component's stylesheet. This is intended to improve maintainability by isolating shared components as a reusable interface, reducing the surface area of similar UI elements by adapting a limited set of common components to support a varied set of use-cases. +A component's class name should **never** be used outside its own folder (with rare exceptions such as [`_z-index.scss`](https://github.com/WordPress/gutenberg/blob/HEAD/packages/base-styles/_z-index.scss)). If you need to inherit styles of another component in your own components, you should render an instance of that other component. At worst, you should duplicate the styles within your own component's stylesheet. This is intended to improve maintainability by isolating shared components as a reusable interface, reducing the surface area of similar UI elements by adapting a limited set of common components to support a varied set of use-cases. #### SCSS File Naming Conventions for Blocks @@ -65,7 +65,7 @@ Examples of styles that appear in both the theme and the editor include gallery ## JavaScript -JavaScript in Gutenberg uses modern language features of the [ECMAScript language specification](https://www.ecma-international.org/ecma-262/) as well as the [JSX language syntax extension](https://reactjs.org/docs/introducing-jsx.html). These are enabled through a combination of preset configurations, notably [`@wordpress/babel-preset-default`](https://github.com/WordPress/gutenberg/tree/master/packages/babel-preset-default) which is used as a preset in the project's [Babel](https://babeljs.io/) configuration. +JavaScript in Gutenberg uses modern language features of the [ECMAScript language specification](https://www.ecma-international.org/ecma-262/) as well as the [JSX language syntax extension](https://reactjs.org/docs/introducing-jsx.html). These are enabled through a combination of preset configurations, notably [`@wordpress/babel-preset-default`](https://github.com/WordPress/gutenberg/tree/HEAD/packages/babel-preset-default) which is used as a preset in the project's [Babel](https://babeljs.io/) configuration. While the [staged process](https://tc39.es/process-document/) for introducing a new JavaScript language feature offers an opportunity to use new features before they are considered complete, **the Gutenberg project and the `@wordpress/babel-preset-default` configuration will only target support for proposals which have reached Stage 4 ("Finished")**. @@ -210,7 +210,7 @@ alert( `My name is ${ name }.` ); - Example: `const hasFocus = ! nodeRef.current?.contains( document.activeElement );` will yield `true` if `nodeRef.current` is not assigned. - See related issue: [#21984](https://github.com/WordPress/gutenberg/issues/21984) - See similar ESLint rule: [`no-unsafe-negation`](https://eslint.org/docs/rules/no-unsafe-negation) -- When assigning a boolean value, observe that optional chaining may produce values which are [falsy](https://developer.mozilla.org/en-US/docs/Glossary/Falsy) (`undefined`, `null`), but not strictly `false`. This can become an issue when the value is passed around in a way where it is expected to be a boolean (`true` or `false`). While it's a common occurrence for booleans—since booleans are often used in ways where the logic considers truthiness and falsyness broadly—these issues can also occur for other optional chaining when eagerly assuming a type resulting from the end of the property access chain. [Type-checking](https://github.com/WordPress/gutenberg/blob/master/packages/README.md#typescript) may help in preventing these sorts of errors. +- When assigning a boolean value, observe that optional chaining may produce values which are [falsy](https://developer.mozilla.org/en-US/docs/Glossary/Falsy) (`undefined`, `null`), but not strictly `false`. This can become an issue when the value is passed around in a way where it is expected to be a boolean (`true` or `false`). While it's a common occurrence for booleans—since booleans are often used in ways where the logic considers truthiness and falsyness broadly—these issues can also occur for other optional chaining when eagerly assuming a type resulting from the end of the property access chain. [Type-checking](https://github.com/WordPress/gutenberg/blob/HEAD/packages/README.md#typescript) may help in preventing these sorts of errors. - Example: `document.body.classList.toggle( 'has-focus', nodeRef.current?.contains( document.activeElement ) );` may wrongly _add_ the class, since [the second argument is optional](https://developer.mozilla.org/en-US/docs/Web/API/DOMTokenList/toggle). If `undefined` is passed, it would not unset the class as it would when `false` is passed. - Example: `` may inadvertently cause warnings in React by toggling between [controlled and uncontrolled inputs](https://reactjs.org/docs/uncontrolled-components.html). This is an easy trap to fall into when eagerly assuming that a result of `trim()` will always return a string value, overlooking the fact the optional chaining may have caused evaluation to abort earlier with a value of `undefined`. @@ -220,7 +220,7 @@ It is preferred to implement all components as [function components](https://rea ## JavaScript Documentation using JSDoc -Gutenberg follows the [WordPress JavaScript Documentation Standards](https://make.wordpress.org/core/handbook/best-practices/inline-documentation-standards/javascript/), with additional guidelines relevant for its distinct use of [import semantics](https://github.com/WordPress/gutenberg/blob/master/docs/contributors/coding-guidelines.md#imports) in organizing files, the [use of TypeScript tooling](https://github.com/WordPress/gutenberg/blob/master/docs/contributors/testing-overview.md#javascript-testing) for types validation, and automated documentation generation using [`@wordpress/docgen`](https://github.com/WordPress/gutenberg/tree/master/packages/docgen). +Gutenberg follows the [WordPress JavaScript Documentation Standards](https://make.wordpress.org/core/handbook/best-practices/inline-documentation-standards/javascript/), with additional guidelines relevant for its distinct use of [import semantics](/docs/contributors/code/coding-guidelines.md#imports) in organizing files, the [use of TypeScript tooling](/docs/contributors/code/testing-overview.md#javascript-testing) for types validation, and automated documentation generation using [`@wordpress/docgen`](https://github.com/WordPress/gutenberg/tree/HEAD/packages/docgen). For additional guidance, consult the following resources: @@ -266,7 +266,7 @@ Note the use of quotes when defining a set of string literals. As in the [JavaSc Use the [TypeScript `import` function](https://www.typescriptlang.org/docs/handbook/type-checking-javascript-files.html#import-types) to import type declarations from other files or third-party dependencies. -Since an imported type declaration can occupy an excess of the available line length and become verbose when referenced multiple times, you are encouraged to create an alias of the external type using a `@typedef` declaration at the top of the file, immediately following [the `import` groupings](https://github.com/WordPress/gutenberg/blob/master/docs/contributors/coding-guidelines.md#imports). +Since an imported type declaration can occupy an excess of the available line length and become verbose when referenced multiple times, you are encouraged to create an alias of the external type using a `@typedef` declaration at the top of the file, immediately following [the `import` groupings](/docs/contributors/code/coding-guidelines.md#imports). ```js /** @typedef {import('@wordpress/data').WPDataRegistry} WPDataRegistry */ @@ -472,6 +472,6 @@ For class components, there is no recommendation for documenting the props of th We use [`phpcs` (PHP_CodeSniffer)](https://github.com/squizlabs/PHP_CodeSniffer) with the [WordPress Coding Standards ruleset](https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards) to run a lot of automated checks against all PHP code in this project. This ensures that we are consistent with WordPress PHP coding standards. -The easiest way to use PHPCS is [local environment](/docs/contributors/getting-started.md#local-environment). Once that's installed, you can check your PHP by running `npm run lint-php`. +The easiest way to use PHPCS is [local environment](/docs/contributors/code/getting-started-with-code-contribution.md#local-environment). Once that's installed, you can check your PHP by running `npm run lint-php`. If you prefer to install PHPCS locally, you should use `composer`. [Install `composer`](https://getcomposer.org/download/) on your computer, then run `composer install`. This will install `phpcs` and `WordPress-Coding-Standards` which you can then run via `composer lint`. diff --git a/docs/contributors/getting-started-native-mobile.md b/docs/contributors/code/getting-started-native-mobile.md similarity index 81% rename from docs/contributors/getting-started-native-mobile.md rename to docs/contributors/code/getting-started-native-mobile.md index b794f70267be14..b748c8880bc6d8 100644 --- a/docs/contributors/getting-started-native-mobile.md +++ b/docs/contributors/code/getting-started-native-mobile.md @@ -1,6 +1,6 @@ # Getting Started for the React Native based Mobile Gutenberg -Welcome! This is the Getting Started guide for the native mobile port of the block editor, targeting Android and iOS devices. Overall, it's a React Native library to be used in parent greenfield or brownfield apps. Continue reading for information on how to build and it! +Welcome! This is the Getting Started guide for the native mobile port of the block editor, targeting Android and iOS devices. Overall, it's a React Native library to be used in parent greenfield or brownfield apps. Continue reading for information on how to build, test, and run it. ## Prerequisites @@ -23,7 +23,7 @@ git clone https://github.com/WordPress/gutenberg.git ## Set up -Before running the demo app, you need to download and install the project dependencies. This is done via the following command: +Note that the commands described here should be run in the top-level directory of the cloned project. Before running the demo app, you need to download and install the project dependencies. This is done via the following command: ``` nvm install --latest-npm @@ -33,7 +33,7 @@ npm ci ## Run ``` -npm run native start +npm run native start:reset ``` Runs the packager (Metro) in development mode. The packager stays running to serve the app bundle to the clients that request it. @@ -72,7 +72,7 @@ To see a list of all of your available iOS devices, use `xcrun simctl list devic ### Troubleshooting -Some times, and especially when tweaking anything in the `package.json`, Babel configuration (`.babelrc`) or the Jest configuration (`jest.config.js`), your changes might seem to not take effect as expected. On those times, you might need to clean various caches before starting the packager. To do that, run the script: `npm run native start:reset`. Other times, you might want to reinstall the NPM packages from scratch and the `npm run native clean:install` script can be handy. +Some times, and especially when tweaking anything in the `package.json`, Babel configuration (`.babelrc`) or the Jest configuration (`jest.config.js`), your changes might seem to not take effect as expected. On those times, you might need to stop the metro bunder process and restart it with `npm run native start:reset`. Other times, you might want to reinstall the NPM packages from scratch and the `npm run native clean:install` script can be handy. ## Developing with Visual Studio Code @@ -102,14 +102,14 @@ Then, open `chrome://inspect` in Chrome to attach the debugger (look into the "R ## Writing and Running Unit Tests -This project is set up to use [jest](https://facebook.github.io/jest/) for tests. You can configure whatever testing strategy you like, but jest works out of the box. Create test files in directories called `__tests__` or with the `.test.js` extension to have the files loaded by jest. See an example test [here](https://github.com/WordPress/gutenberg/blob/master/packages/react-native-editor/src/test/api-fetch-setup.test.js). The [jest documentation](https://facebook.github.io/jest/docs/en/getting-started.html) is also a wonderful resource, as is the [React Native testing tutorial](https://facebook.github.io/jest/docs/en/tutorial-react-native.html). +This project is set up to use [jest](https://facebook.github.io/jest/) for tests. You can configure whatever testing strategy you like, but jest works out of the box. Create test files in directories called `__tests__` or with the `.test.js` extension to have the files loaded by jest. See an example test [here](https://github.com/WordPress/gutenberg/blob/HEAD/packages/react-native-editor/src/test/api-fetch-setup.test.js). The [jest documentation](https://facebook.github.io/jest/docs/en/getting-started.html) is also a wonderful resource, as is the [React Native testing tutorial](https://facebook.github.io/jest/docs/en/tutorial-react-native.html). ## UI Tests This repository uses Appium to run UI tests. The tests live in `__device-tests__` and are written using Appium to run tests against simulators and real devices. To run these you'll need to check off a few things: - When running the tests, you'll need to ensure the Metro bundler (`npm run native start`) is not running. -- [Appium CLI](https://github.com/appium/appium/blob/master/docs/en/about-appium/getting-started.md) installed and available globally. We also recommend using [appium-doctor](https://github.com/appium/appium-doctor) to ensure all of Appium's dependencies are good to go. You don't have to worry about starting the server yourself, the tests handle starting the server on port 4723, just be sure that the port is free or feel free to change the port number in the test file. +- [Appium CLI](https://github.com/appium/appium/blob/HEAD/docs/en/about-appium/getting-started.md) installed and available globally. We also recommend using [appium-doctor](https://github.com/appium/appium-doctor) to ensure all of Appium's dependencies are good to go. You don't have to worry about starting the server yourself, the tests handle starting the server on port 4723, just be sure that the port is free or feel free to change the port number in the test file. - For iOS a simulator should automatically launch but for Android you'll need to have an emulator _with at least platform version 8.0_ fired up and running. Then, to run the UI tests on iOS: diff --git a/docs/contributors/getting-started.md b/docs/contributors/code/getting-started-with-code-contribution.md similarity index 92% rename from docs/contributors/getting-started.md rename to docs/contributors/code/getting-started-with-code-contribution.md index ddd38be4d16931..f5384b1bd05874 100644 --- a/docs/contributors/getting-started.md +++ b/docs/contributors/code/getting-started-with-code-contribution.md @@ -1,12 +1,12 @@ -# Getting Started +# Getting Started With Code Contribution -The following guide is for setting up your local environment to contribute to the Gutenberg project. There is significant overlap between an environment to contribute and an environment used to extend the WordPress block editor. You can review the [Development Environment tutorial](/docs/designers-developers/developers/tutorials/devenv/readme.md) for additional setup information. +The following guide is for setting up your local environment to contribute to the Gutenberg project. There is significant overlap between an environment to contribute and an environment used to extend the WordPress block editor. You can review the [Development Environment tutorial](/docs/getting-started/tutorials/devenv/README.md) for additional setup information. ## Development Tools (Node) Gutenberg is a JavaScript project and requires [Node.js](https://nodejs.org/). The project is built using the latest active LTS release of node, and the latest version of NPM. See the [LTS release schedule](https://github.com/nodejs/Release#release-schedule) for details. -We recommend using the [Node Version Manager](https://github.com/nvm-sh/nvm) (nvm) since it is the easiest way to install and manage node for macOS, Linux, and Windows 10 using WSL2. See [our Development Tools guide](/docs/designers-developers/developers/tutorials/devenv/readme.md#development-tools) or the Nodejs site for additional installation instructions. +We recommend using the [Node Version Manager](https://github.com/nvm-sh/nvm) (nvm) since it is the easiest way to install and manage node for macOS, Linux, and Windows 10 using WSL2. See [our Development Tools guide](/docs/getting-started/tutorials/devenv/README.md#development-tools) or the Nodejs site for additional installation instructions. After installing Node, you can build Gutenberg by running the following from within the cloned repository: @@ -34,7 +34,7 @@ The [wp-env package](/packages/env/README.md) was developed with the Gutenberg p By default, `wp-env` can run in a plugin directory to create and run a WordPress environment, mounting and activating the plugin automatically. You can also configure `wp-env` to use existing installs, multiple plugins, or themes. See the [wp-env package](/packages/env/README.md#wp-envjson) for complete documentation. -If you don't already have it, you'll need to install Docker and Docker Compose in order to use `wp-env`. See the [Development Environment tutorial for additional details](/docs/designers-developers/developers/tutorials/devenv/readme.md). +If you don't already have it, you'll need to install Docker and Docker Compose in order to use `wp-env`. See the [Development Environment tutorial for additional details](/docs/getting-started/tutorials/devenv/README.md). Once Docker is installed and running: To install WordPress, run the following from within the cloned gutenberg directory: @@ -138,7 +138,7 @@ The Gutenberg repository also includes [Storybook](https://storybook.js.org/) in You can launch Storybook by running `npm run storybook:dev` locally. It will open in your browser automatically. -You can also test Storybook for the current `master` branch on GitHub Pages: [https://wordpress.github.io/gutenberg/](https://wordpress.github.io/gutenberg/) +You can also test Storybook for the current `trunk` branch on GitHub Pages: [https://wordpress.github.io/gutenberg/](https://wordpress.github.io/gutenberg/) ## Developer Tools @@ -146,13 +146,13 @@ We recommend configuring your editor to automatically check for syntax and lint ### EditorConfig -[EditorConfig](https://editorconfig.org/) defines a standard configuration for setting up your editor, for example using tabs instead of spaces. You should install the [EditorConfig for VS Code](https://marketplace.visualstudio.com/items?itemName=editorconfig.editorconfig) extension and it will automatically configure your editor to match the rules defined in [.editorconfig](https://github.com/WordPress/gutenberg/blob/master/.editorconfig). +[EditorConfig](https://editorconfig.org/) defines a standard configuration for setting up your editor, for example using tabs instead of spaces. You should install the [EditorConfig for VS Code](https://marketplace.visualstudio.com/items?itemName=editorconfig.editorconfig) extension and it will automatically configure your editor to match the rules defined in [.editorconfig](https://github.com/WordPress/gutenberg/blob/HEAD/.editorconfig). ### ESLint [ESLint](https://eslint.org/) statically analyzes the code to find problems. The lint rules are integrated in the continuous integration process and must pass to be able to commit. You should install the [ESLint Extension](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) for Visual Studio Code, see eslint docs for [more editor integrations](https://eslint.org/docs/user-guide/integrations). -With the extension installed, ESLint will use the [.eslintrc.js](https://github.com/WordPress/gutenberg/blob/master/.eslintrc.js) file in the root of the Gutenberg repository for formatting rules. It will highlight issues as you develop, you can also set the following preference to fix lint rules on save. +With the extension installed, ESLint will use the [.eslintrc.js](https://github.com/WordPress/gutenberg/blob/HEAD/.eslintrc.js) file in the root of the Gutenberg repository for formatting rules. It will highlight issues as you develop, you can also set the following preference to fix lint rules on save. ```json "editor.codeActionsOnSave": { diff --git a/docs/contributors/git-workflow.md b/docs/contributors/code/git-workflow.md similarity index 87% rename from docs/contributors/git-workflow.md rename to docs/contributors/code/git-workflow.md index 2e4926d593578a..38741e3c1ba21d 100644 --- a/docs/contributors/git-workflow.md +++ b/docs/contributors/code/git-workflow.md @@ -49,7 +49,7 @@ This will create a directory called `gutenberg` with all the files for the proje git switch -c update/my-branch ``` -**Step 4**: Make the code changes. Build, confirm, and test your change thoroughly. See [coding guidelines](/docs/contributors/coding-guidelines.md) and [testing overview](/docs/contributors/testing-overview.md) for guidance. +**Step 4**: Make the code changes. Build, confirm, and test your change thoroughly. See [coding guidelines](/docs/contributors/code/coding-guidelines.md) and [testing overview](/docs/contributors/code/testing-overview.md) for guidance. **Step 5**: Commit your change with a [good commit message](https://make.wordpress.org/core/handbook/best-practices/commit-messages/). This will commit your change to your local copy of the repository. @@ -60,7 +60,7 @@ git commit -m "Your Good Commit Message" path/to/FILE **Step 6**: Push your change up to GitHub. The change will be pushed to your fork of the repository on the GitHub ```bash -git push -u origin upgrade/my-branch +git push -u origin update/my-branch ``` **Step 7**: Go to your forked repository on GitHub -- it will automatically detect the change and give you a link to create a pull request. @@ -95,15 +95,15 @@ When many different people are working on a project simultaneously, pull request There are two ways to do this: merging and rebasing. In Gutenberg, the recommendation is to rebase. Rebasing means rewriting your changes as if they're happening on top of the main line of development. This ensures the commit history is always clean and linear. Rebasing can be performed as many times as needed while you're working on a pull request. **Do share your work early on** by opening a pull request and keeping your history rebase as you progress. -The main line of development is known as the `master` branch. If you have a pull-request branch that cannot be merged into `master` due to a conflict (this can happen for long-running pull requests), then in the course of rebasing you'll have to manually resolve any conflicts in your local copy. Learn more in [section _Perform a rebase_](https://github.com/edx/edx-platform/wiki/How-to-Rebase-a-Pull-Request#perform-a-rebase) of _How to Rebase a Pull Request_. +The main line of development is known as the `trunk` branch. If you have a pull-request branch that cannot be merged into `trunk` due to a conflict (this can happen for long-running pull requests), then in the course of rebasing you'll have to manually resolve any conflicts in your local copy. Learn more in [section _Perform a rebase_](https://github.com/edx/edx-platform/wiki/How-to-Rebase-a-Pull-Request#perform-a-rebase) of _How to Rebase a Pull Request_. Once you have resolved any conflicts locally you can update the pull request with `git push --force-with-lease`. Using the `--force-with-lease` parameter is important to guarantee that you don't accidentally overwrite someone else's work. -To sum it up, you need to fetch any new changes in the repository, rebase your branch on top of `master`, and push the result back to the repository. These are the corresponding commands: +To sum it up, you need to fetch any new changes in the repository, rebase your branch on top of `trunk`, and push the result back to the repository. These are the corresponding commands: ```sh git fetch -git rebase master +git rebase trunk git push --force-with-lease origin your-branch-name ``` @@ -126,8 +126,8 @@ To sync your fork, you first need to fetch the upstream changes and merge them i ``` sh git fetch upstream -git checkout master -git merge upstream/master +git checkout trunk +git merge upstream/trunk ``` Once your local copy is updated, push your changes to update your fork on GitHub: @@ -136,4 +136,4 @@ Once your local copy is updated, push your changes to update your fork on GitHub git push ``` -The above commands will update your `master` branch from _upstream_. To update any other branch replace `master` with the respective branch name. +The above commands will update your `trunk` branch from _upstream_. To update any other branch replace `trunk` with the respective branch name. diff --git a/docs/contributors/grammar.md b/docs/contributors/code/grammar.md similarity index 100% rename from docs/contributors/grammar.md rename to docs/contributors/code/grammar.md diff --git a/docs/contributors/managing-packages.md b/docs/contributors/code/managing-packages.md similarity index 74% rename from docs/contributors/managing-packages.md rename to docs/contributors/code/managing-packages.md index 9032af8cf3acbe..e89298a10ada6c 100644 --- a/docs/contributors/managing-packages.md +++ b/docs/contributors/code/managing-packages.md @@ -1,8 +1,8 @@ # Managing Packages -This repository uses [lerna] to manage Gutenberg modules and publish them as packages to [npm]. This enforces certain steps in the workflow which are described in details in [packages](https://github.com/WordPress/gutenberg/blob/master/packages/README.md) documentation. +This repository uses [lerna] to manage Gutenberg modules and publish them as packages to [npm]. This enforces certain steps in the workflow which are described in details in [packages](https://github.com/WordPress/gutenberg/blob/HEAD/packages/README.md) documentation. -Maintaining dozens of npm packages is difficult—it can be tough to keep track of changes. That's why we use `CHANGELOG.md` files for each package to simplify the release process. As a contributor, you should add an entry to the aforementioned file each time you contribute adding production code as described in [Maintaining Changelogs](https://github.com/WordPress/gutenberg/blob/master/packages/README.md#maintaining-changelogs) section. +Maintaining dozens of npm packages is difficult—it can be tough to keep track of changes. That's why we use `CHANGELOG.md` files for each package to simplify the release process. As a contributor, you should add an entry to the aforementioned file each time you contribute adding production code as described in [Maintaining Changelogs](https://github.com/WordPress/gutenberg/blob/HEAD/packages/README.md#maintaining-changelogs) section. [lerna]: https://lerna.js.org [npm]: https://www.npmjs.com/ diff --git a/docs/contributors/native-mobile.md b/docs/contributors/code/native-mobile.md similarity index 85% rename from docs/contributors/native-mobile.md rename to docs/contributors/code/native-mobile.md index a9de2818125820..91f4927a1fa6c2 100644 --- a/docs/contributors/native-mobile.md +++ b/docs/contributors/code/native-mobile.md @@ -4,7 +4,7 @@ Intertwined with the web codepaths, the Gutenberg repo also includes the [React ## Running Gutenberg Mobile on Android and iOS -For instructions on how to run the **Gutenberg Mobile Demo App** on Android or iOS, see [Getting Started for the React Native based Mobile Gutenberg](/docs/contributors/getting-started-native-mobile.md) +For instructions on how to run the **Gutenberg Mobile Demo App** on Android or iOS, see [Getting Started for the React Native based Mobile Gutenberg](/docs/contributors/code/getting-started-with-code-contribution-native-mobile.md) Also, the mobile client is packaged and released via the [official WordPress apps](https://wordpress.org/mobile/). Even though the build pipeline is slightly different then the mobile demo apps and lives in its own repo for now ([here's the native mobile repo](https://github.com/wordpress-mobile/gutenberg-mobile)), the source code itself is taken directly from this repo and the "web" side codepaths. @@ -21,11 +21,11 @@ Our tooling isn't as good yet as we'd like to and it's hard to have a good aware If you encounter a failed Android/iOS test on your pull request, we recommend the following steps: 1. Re-running the failed GitHub Action job ([guide for how to re-run](https://docs.github.com/en/actions/configuring-and-managing-workflows/managing-a-workflow-run#viewing-your-workflow-history)) - This should fix failed tests the majority of the time. Cases where you need to re-run tests for a pass should go down in the near future as flakiness in tests is actively being worked on. See the following GitHub issue for updated info on known failures: https://github.com/WordPress/gutenberg/issues/23949 -2. You can check if the test is failing locally by following the steps to run the E2E test on your machine from the [mobile getting started guide](/docs/contributors/getting-started-native-mobile.md#ui-tests), with even more relevant info in the [relevant directory README.md](https://github.com/WordPress/gutenberg/tree/master/packages/react-native-editor/__device-tests__#running-the-tests-locally) +2. You can check if the test is failing locally by following the steps to run the E2E test on your machine from the [mobile getting started guide](/docs/contributors/code/getting-started-with-code-contribution-native-mobile.md#ui-tests), with even more relevant info in the [relevant directory README.md](https://github.com/WordPress/gutenberg/tree/HEAD/packages/react-native-editor/__device-tests__#running-the-tests-locally) 3. In addition to reading the logs from the E2E test, you can download a video recording from the Artifacts section of the GitHub job that may have additional useful information. 4. Check if any changes in your PR would require corresponding changes to `.native.js` versions of files. 5. Lastly, if you're stuck on a failing mobile test, feel free to reach out to contributors on Slack in the #mobile or #core-editor chats in the WordPress Core Slack, [free to join](https://make.wordpress.org/chat/). ## Debugging the native mobile unit tests -Follow the instructions in [Native mobile testing](/docs/contributors/testing-overview.md#native-mobile-testing) to locally debug the native mobile unit tests when needed. +Follow the instructions in [Native mobile testing](/docs/contributors/code/testing-overview.md#native-mobile-testing) to locally debug the native mobile unit tests when needed. diff --git a/docs/contributors/release.md b/docs/contributors/code/release.md similarity index 52% rename from docs/contributors/release.md rename to docs/contributors/code/release.md index 97bf6d2acb23e3..c08bf5cdde81c0 100644 --- a/docs/contributors/release.md +++ b/docs/contributors/code/release.md @@ -2,7 +2,9 @@ This Repository is used to perform several types of releases. This document serves as a checklist for each one of these. It is helpful if you'd like to understand the different workflows. -To release Gutenberg, you need commit access to the [WordPress.org plugin repository][plugin repository] as well as being part of the [WordPress organization at npm](https://www.npmjs.com/org/wordpress). 🙂 +To release a stable version of the Gutenberg plugin, you need approval from a member of the [`gutenberg-core` team](https://github.com/orgs/WordPress/teams/gutenberg-core) for the final step of the release process (upload to the WordPress.org plugin repo -- see below). If you aren't a member yourself, make sure to contact one ahead of time so they'll be around at the time of the release. + +To release Gutenberg's npm packages, you need to be part of the [WordPress organization at npm](https://www.npmjs.com/org/wordpress). 🙂 ## Plugin Releases @@ -10,9 +12,9 @@ To release Gutenberg, you need commit access to the [WordPress.org plugin reposi We release a new major version approximately every two weeks. The current and next versions are [tracked in GitHub milestones](https://github.com/WordPress/gutenberg/milestones), along with each version's tagging date (the day when _the release candidate_ is to be tagged). -- **On the date of the current milestone**, we publish a release candidate and make it available for plugin authors and users to test. If any regressions are found with a release candidate, a new one can be published. On this date, all remaining PRs on the milestone are moved automatically to the next release. Release candidates should be versioned incrementally, starting with `-rc.1`, then `-rc.2`, and so on. +- **On the date of the current milestone**, we publish a release candidate and make it available for plugin authors and users to test. If any regressions are found with a release candidate, a new one can be published. On this date, all remaining PRs on the milestone are moved automatically to the next release. Release candidates should be versioned incrementally, starting with `-rc.1`, then `-rc.2`, and so on. -- **Two days after the first release candidate**, the stable version is created based on the last release candidate and any necessary regression fixes. Once the stable version is released, a post [like this](https://make.wordpress.org/core/2019/06/26/whats-new-in-gutenberg-26th-june/) describing the changes and performing a [performance audit](/docs/block-editor/contributors/testing-overview/#performance-testing) is published. +- **One week after the first release candidate**, the stable version is created based on the last release candidate and any necessary regression fixes. Once the stable version is released, a post [like this](https://make.wordpress.org/core/2019/06/26/whats-new-in-gutenberg-26th-june/) describing the changes and performing a [performance audit](/docs/block-editor/contributors/testing-overview/#performance-testing) is published. If critical bugs are discovered on stable versions of the plugin, patch versions can be released at any time. @@ -34,9 +36,13 @@ To release a stable version, run: During the release process, you'll be asked to provide: -- A changelog: prepare one beforehand by following the instructions below. -- A [personal access token](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line): have one ready beforehand by visiting [this page](https://github.com/settings/tokens/new?scopes=repo,admin:org,write:packages), if you haven't got one yet. -- User and password for your GitHub account: if 2FA is enabled for your account (it should), you need to provide a personal access token instead of password (you can use the one necessary for the release). +- A changelog: prepare one beforehand by following the instructions below. +- A [personal access token](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line): have one ready beforehand by visiting [this page](https://github.com/settings/tokens/new?scopes=repo,admin:org,write:packages), if you haven't got one yet. +- User and password for your GitHub account: if 2FA is enabled for your account (it should), you need to provide a personal access token instead of password (you can use the one necessary for the release). + +The release script will create a `git` tag for the release and push it to GitHub. This triggers a GitHub workflow that builds the plugin, creates a release draft (based on the Changelog), and attaches the plugin zip. This will take a couple of minutes. You will then find the release draft at https://github.com/WordPress/gutenberg/releases. You can edit it further (but note that the changes won't be propagated to `changelog.txt`). Once you're happy with it, press the 'Publish' button. + +If you're releasing a stable version (rather than an RC), this will trigger a GitHub action that will upload the plugin to the WordPress.org plugin repository (SVN). This action needs approval by a member of the [`gutenberg-core` team](https://github.com/orgs/WordPress/teams/gutenberg-core). Locate the ["Upload Gutenberg plugin to WordPress.org plugin repo" workflow](https://github.com/WordPress/gutenberg/actions/workflows/upload-release-to-plugin-repo.yml) for the new version, and have it [approved](https://docs.github.com/en/actions/managing-workflow-runs/reviewing-deployments#approving-or-rejecting-a-job). ### Manual Release Process @@ -59,24 +65,26 @@ To generate a changelog for a release, use the changelog generator tool: npm run changelog ``` -By default, this will search for and organize all pull requests associated with the milestone for the next version of the project. +By default, this will search for and organize all pull requests associated with the milestone for the next version of the project. To override the default behavior, you can pass one or both of the following options. Remember to use `--` to let NPM pass the options to the script. -- `--milestone `: Provide the title of the milestone for which the changelog should be generated. This should exactly match the title as shown on [the milestones page](https://github.com/WordPress/gutenberg/milestones). - - Example: `npm run changelog -- --milestone="Gutenberg 8.1"` -- `--token `: Provide a [GitHub personal access token](https://github.com/settings/tokens) for authenticating requests. This should only be necessary if you run the script frequently enough to been blocked by [rate limiting](https://developer.github.com/v3/#rate-limiting). - - Example: `npm run changelog -- --token="..."` +- `--milestone `: Provide the title of the milestone for which the changelog should be generated. This should exactly match the title as shown on [the milestones page](https://github.com/WordPress/gutenberg/milestones). + - Example: `npm run changelog -- --milestone="Gutenberg 8.1"` +- `--token `: Provide a [GitHub personal access token](https://github.com/settings/tokens) for authenticating requests. This should only be necessary if you run the script frequently enough to been blocked by [rate limiting](https://developer.github.com/v3/#rate-limiting). + - Example: `npm run changelog -- --token="..."` +- `--unreleased`: Only list PRs that have been closed after the latest release in the milestone's series has been published. In other words, only list PRs that haven't been part of a release yet. + - Example: `npm run changelog -- --milestone="Gutenberg 9.8" --unreleased`. If the latest version in the 9.8 series is 9.8.3, only show PRs for the in the 9.8 series that were closed (merged) after 9.8.3 was published. The script will output a generated changelog, grouped by pull request label. _Note that this is intended to be a starting point for release notes_. You will still want to manually review and curate the changelog entries. Guidelines for proof-reading include: -- Fix spelling errors or clarify wording. Phrasing should be easy to understand where the intended audience are those who use the plugin or are keeping up with ongoing development. -- Create new groupings as applicable, and move pull requests between. -- When multiple pull requests relate to the same task (such as a follow-up pull request), try to combine them to a single entry. -- If subtasks of a related set of pull requests are substantial, consider organizing as entries in a nested list. -- Remove mobile app pull request entries. +- Fix spelling errors or clarify wording. Phrasing should be easy to understand where the intended audience are those who use the plugin or are keeping up with ongoing development. +- Create new groupings as applicable, and move pull requests between. +- When multiple pull requests relate to the same task (such as a follow-up pull request), try to combine them to a single entry. +- If subtasks of a related set of pull requests are substantial, consider organizing as entries in a nested list. +- Remove mobile app pull request entries. Once you have cleaned up the changelog, choose a few features to highlight in the release post and record an animation of them in use. @@ -86,10 +94,10 @@ Compile this to a draft post on [make.wordpress.org/core](https://make.wordpress ##### Creating the Release Branch -For each milestone (let's assume it's `x.x` here), a release branch is used to release all RCs and minor releases. For the first RC of the milestone, a release branch is created from master. +For each milestone (let's assume it's `x.x` here), a release branch is used to release all RCs and minor releases. For the first RC of the milestone, a release branch is created from trunk. ``` -git checkout master +git checkout trunk git checkout -b release/x.x git push origin release/x.x ``` @@ -98,7 +106,7 @@ git push origin release/x.x 1. Checkout the `release/x.x` branch. 2. Create [a commit like this](https://github.com/WordPress/gutenberg/pull/13125/commits/13fa651dadc2472abb9b95f80db9d5f23e63ae9c), bumping the version number in `gutenberg.php`, `package.json`, and `package-lock.json` to `x.x.0-rc.1`. -3. Create a Pull Request from the release branch into `master` using the changelog as a description and ensure the tests pass properly. +3. Create a Pull Request from the release branch into `trunk` using the changelog as a description and ensure the tests pass properly. 4. Tag the RC version. `git tag vx.x.0-rc.1` from the release branch. 5. Push the tag `git push --tags`. 6. Merge the version bump pull request and avoid removing the release branch. @@ -121,16 +129,16 @@ Here's an example [release candidate page](https://github.com/WordPress/gutenber #### Creating Release Candidate Patches (done via `git cherry-pick`) -If a bug is found in a release candidate and a fix is committed to `master`, we should include that fix in a new release candidate. To do this you'll need to use `git cherry-pick` to add these changes to the milestone's release branch. This way only fixes are added to the release candidate and not all the new code that has landed on `master` since tagging: +If a bug is found in a release candidate and a fix is committed to `trunk`, we should include that fix in a new release candidate. To do this you'll need to use `git cherry-pick` to add these changes to the milestone's release branch. This way only fixes are added to the release candidate and not all the new code that has landed on `trunk` since tagging: 1. Checkout the corresponding release branch with: `git checkout release/x.x`. 2. Cherry-pick fix commits (in chronological order) with `git cherry-pick [SHA]`. 3. Create [a commit like this](https://github.com/WordPress/gutenberg/pull/13125/commits/13fa651dadc2472abb9b95f80db9d5f23e63ae9c), bumping the version number in `gutenberg.php`, `package.json`, and `package-lock.json` to `x.x.0-rc.2`. -4. Create a Pull Request from the release branch into `master` using the changelog as a description and ensure the tests pass properly. Note that if there there are merge conflicts, Travis CI will not run on the PR. Run tests locally using `npm run test` and `npm run test-e2e` if this happens. +4. Create a Pull Request from the release branch into `trunk` using the changelog as a description and ensure the tests pass properly. Note that if there there are merge conflicts, Travis CI will not run on the PR. Run tests locally using `npm run test` and `npm run test-e2e` if this happens. 5. Tag the RC version. `git tag vx.x.0-rc.2` from the release branch. 6. Push the tag `git push --tags`. 7. Create a branch for bumping the version number. `git checkout -b bump/x.x`. -8. Create a Pull Request from the `bump/x.x` branch into `master` using the +8. Create a Pull Request from the `bump/x.x` branch into `trunk` using the changelog as a description. 9. Merge the version bump pull request. 10. Follow the steps in [build the plugin](#build-the-plugin) and [publish the release on GitHub](#publish-the-release-on-github). @@ -160,12 +168,12 @@ Creating a release involves: 1. Checkout the release branch `git checkout release/x.x`. -**Note:** This branch should never be removed or rebased. When we want to merge something from it to master and conflicts exist/may exist we use a temporary branch `bump/x.x`. +**Note:** This branch should never be removed or rebased. When we want to merge something from it to trunk and conflicts exist/may exist we use a temporary branch `bump/x.x`. 2. Create [a commit like this](https://github.com/WordPress/gutenberg/commit/00d01049685f11f9bb721ad3437cb928814ab2a2#diff-b9cfc7f2cdf78a7f4b91a753d10865a2), removing the `-rc.X` from the version number in `gutenberg.php`, `package.json`, and `package-lock.json`. 3. Create a new branch called `bump/x.x` from `release/x.x` and switch to it: `git checkout -b bump/x.x`. -4. Create a pull request from `bump/x.x` to `master`. Verify the continuous integrations tests pass, before continuing to the next step even if conflicts exist. -5. Rebase `bump/x.x` against `origin/master` using `git fetch origin && git rebase origin/master`. +4. Create a pull request from `bump/x.x` to `trunk`. Verify the continuous integrations tests pass, before continuing to the next step even if conflicts exist. +5. Rebase `bump/x.x` against `origin/trunk` using `git fetch origin && git rebase origin/trunk`. 6. Force push the branch `bump/x.x` using `git push --force-with-lease`. 7. Switch to the `release/x.x` branch. Tag the version from the release branch `git tag vx.x.0`. 8. Push the tag `git push --tags`. @@ -190,29 +198,38 @@ Creating a release involves: You'll need to use Subversion to publish the plugin to WordPress.org. 1. Do an SVN checkout of `https://wordpress.org/plugins/gutenberg/trunk`: - * If this is your first checkout, run: `svn checkout https://plugins.svn.wordpress.org/gutenberg/trunk` - * If you already have a copy, run: `svn up` + +- If this is your first checkout, run: `svn checkout https://plugins.svn.wordpress.org/gutenberg/trunk` +- If you already have a copy, run: `svn up` + 2. Delete the contents except for the `readme.txt` and `changelog.txt` files (these files don’t exist in the `git` repo, only in Subversion). 3. Extract the contents of the zip file. 4. Edit `readme.txt`, replacing the changelog for the previous version with the current release's changelog. 5. Add the changelog for the current release to `changelog.txt`. 6. Add new files/remove deleted files from the repository: + ```bash # Add new files: -svn st | grep '^\?' | awk '{print $2}' | xargs svn add +svn st | grep '^\?' | awk '{print $2}' | xargs svn add # add the -r option to xargs if you use a linux-based OS # Delete old files: -svn st | grep '^!' | awk '{print $2}' | xargs svn rm +svn st | grep '^!' | awk '{print $2}' | xargs svn rm # add the -r option to xargs if you use a linux-based OS ``` + 7. Commit the new version: + ```bash # Replace X.X.X with your version: svn ci -m "Committing Gutenberg version X.X.X" ``` + 8. Tag the new version: + ```bash svn cp https://plugins.svn.wordpress.org/gutenberg/trunk https://plugins.svn.wordpress.org/gutenberg/tags/X.X.X -m "Tagging Gutenberg version X.X.X" ``` + 9. Edit `readme.txt` to point to the new tag. The **Stable version** header in `readme.txt` should be updated to match the new release version number. After updating and committing that, the new version should be released: + ```bash svn ci -m "Releasing Gutenberg version X.X.X" ``` @@ -228,12 +245,21 @@ You should check that folks are able to install the new version from their Dashb If you don't have access to [make.wordpress.org/core](https://make.wordpress.org/core/), ping [someone on the Gutenberg Core team](https://github.com/orgs/WordPress/teams/gutenberg-core) in the [WordPress #core-editor Slack channel](https://wordpress.slack.com/messages/C02QB2JS7) to publish the post. -## Packages Releases and WordPress Core Updates +## Packages Releases to npm and WordPress Core Updates The Gutenberg repository mirrors the [WordPress SVN repository](https://make.wordpress.org/core/handbook/about/release-cycle/) in terms of branching for each SVN branch, a corresponding Gutenberg `wp/*` branch is created: -- The `wp/trunk` branch contains all the packages that are published and used in the `trunk` branch of WordPress. -- A Gutenberg branch targeting a specific WordPress major release (including its further minor increments) is created (example `wp/5.2`) based on the `wp/trunk` Gutenberg branch when the corresponding WordPress release branch is created. (This usually happens when the first `RC` of the next WordPress major version is released). +- The `wp/trunk` branch contains the same version of packages published to npm with the `latest` distribution tag. The WordPress core consumes those packages directly in the `trunk` branch and uses them for public releases. +- The `wp/next` branch contains the same version of packages published to npm with the `next` distribution tag. Projects should use those packages for development purposes only. +- A Gutenberg branch targeting a specific WordPress major release (including its further minor increments) is created (example `wp/5.2`) based on the `wp/trunk` Gutenberg branch when the corresponding WordPress release branch is created. (This usually happens when the first `RC` of the next WordPress major version is released). + +Release types and their schedule: + +- [Synchronizing WordPress Trunk](#synchronizing-wordpress-trunk) (`latest` dist tag) – when there is no "feature-freeze" mode in WordPress Core, then publishing happens every two weeks based on the new stable version of the Gutenberg plugin. Otherwise, only bug fixes get manually included and published to npm before every next beta and RC version of the following WordPress release. +- [Minor WordPress Releases](#minor-wordpress-releases) (`patch` dist tag) – only when bug fixes or security releases need to be backported into WordPress Core. +- [Development Releases](#development-releases) (`next` dist tag) – at least every two weeks when the RC version for the Gutenberg plugin is released. + +There is also an option to perform [Standalone Package Releases](#standalone-package-releases) at will. It should be reserved only for critical bug fixes or security releases that must be published to _npm_ outside of a regular WordPress release cycle. ### Synchronizing WordPress Trunk @@ -241,7 +267,7 @@ For each Gutenberg plugin release, WordPress trunk should be synchronized. Note The process has three steps: 1) update the `wp/trunk` branch within the Gutenberg repo 2) publish the new package versions to npm 3) update the WordPress `trunk` branch. -The first step is automated via `./bin/plugin/cli.js npm-stable` command. You only have to run the command, but, for the record, the manual process would look like this: +The first step is automated via `./bin/plugin/cli.js npm-latest` command. You only have to run the command, but, for the record, the manual process would look very close to the following steps: 1. Ensure the WordPress `trunk` branch is open for enhancements. 2. Get the last published Gutenberg release branch with `git fetch`. @@ -249,26 +275,22 @@ The first step is automated via `./bin/plugin/cli.js npm-stable` command. You on 4. Remove all files from the current branch: `git rm -r .`. 5. Check out all the files from the release branch: `git checkout release/x.x -- .`. 6. Commit all changes to the `wp/trunk` branch with `git commit -m "Merge changes published in the Gutenberg plugin vX.X release"` and push to the repository. -7. Update the `CHANGELOG.md` files of the packages with the new publish version calculated and commit to the `wp/trunk` branch. Assuming the package versions are written using this format `major.minor.patch`, make sure to bump at least the `minor` version number. For example, if the CHANGELOG of the package to be released indicates that the next unreleased version is `5.6.1`, choose `5.7.0` as a version in case of `minor` version. This is important as the patch version numbers should be reserved in case bug fixes are needed for a minor WordPress release (see below). - -Once the command is finished, you can start the second part: publishing the npm packages. +7. Update the `CHANGELOG.md` files of the packages with the new publish version calculated and commit to the `wp/trunk` branch. Assuming the package versions are written using this format `major.minor.patch`, make sure to bump at least the `minor` version number after every major WordPress release. For example, if the CHANGELOG of the package to be released indicates that the next unreleased version is `5.6.1`, choose `5.7.0` as a version in case of `minor` version. This is important as the patch version numbers should be reserved in case bug fixes are needed for a minor WordPress release (see below). +8. Log-in to npm via the console: `npm login`. Note that you should have 2FA enabled. +9. From the `wp/trunk` branch, install npm dependencies with `npm ci`. +10. Run the script `npm run publish:prod`. + - When asked for the version numbers to choose for each package pick the values of the updated CHANGELOG files. + - You'll be asked for your One-Time Password (OTP) a couple of times. This is the code from the 2FA authenticator app you use. Depending on how many packages are to be released you may be asked for more than one OTP, as they tend to expire before all packages are released. + - If the publishing process ends up incomplete (perhaps because it timed-out or an bad OTP was introduce) you can resume it via [`lerna publish from-package`](https://github.com/lerna/lerna/tree/HEAD/commands/publish#bump-from-package). -1. Update your local `wp/trunk` branch with the latest changes pushed to GitHub. -2. Log-in to npm via the console: `npm login`. Note that you should have 2FA enabled. -3. From the `wp/trunk` branch, run the script `npm run publish:prod`. - - When asked for the version numbers to choose for each package pick the values of the updated CHANGELOG files. - - You'll be asked for your One-Time Password (OTP) a couple of times. This is the code from the 2FA authenticator app you use. Depending on how many packages are to be released you may be asked for more than one OTP, as they tend to expire before all packages are released. - - If the publishing process ends up incomplete (perhaps because it timed-out or an bad OTP was introduce) you can resume it via [`lerna publish from-package`](https://github.com/lerna/lerna/tree/master/commands/publish#bump-from-package). -4. Cherry-pick the commits created by lerna ("Publish" and the CHANGELOG update) into the `master` branch of Gutenberg. - -Finally, now that the npm packages are ready, a patch can be created and committed into WordPress `trunk`. +Finally, now that the npm packages are ready, a patch can be created and committed into WordPress `trunk`. You should also cherry-pick the commits created by lerna ("Publish" and the CHANGELOG update) into the `trunk` branch of Gutenberg. ### Minor WordPress Releases The following workflow is needed when bug fixes or security releases need to be backported into WordPress Core. This can happen in a few use-cases: -- During the `beta` and the `RC` period of the WordPress release cycle. -- For WordPress minor releases and WordPress security releases (example `5.1.1`). +- During the `beta` and the `RC` period of the WordPress release cycle. +- For WordPress minor releases and WordPress security releases (example `5.1.1`). 1. Check out the relevant WordPress major branch (If the minor release is 5.2.1, check out `wp/5.2`). 2. Create a feature branch from that branch, and cherry-pick the merge commits for the needed bug fixes onto it. @@ -284,123 +306,133 @@ Now, the branch is ready to be used to publish the npm packages. **Note:** For WordPress `5.0` and WordPress `5.1`, a different release process was used. This means that when choosing npm package versions targeting these two releases, you won't be able to use the next `patch` version number as it may have been already used. You should use the "metadata" modifier for these. For example, if the last published package version for this WordPress branch was `5.6.1`, choose `5.6.1+patch.1` as a version. 3. Update the `CHANGELOG.md` files of the published packages with the new released versions and commit to the corresponding branch (Example `wp/5.2`). -4. Cherry-pick the CHANGELOG update commits into the `master` branch of Gutenberg. +4. Cherry-pick the CHANGELOG update commits into the `trunk` branch of Gutenberg. Now, the npm packages should be ready and a patch can be created and committed into the corresponding WordPress SVN branch. ### Standalone Package Releases -The following workflow is needed when packages require bug fixes or security releases to be published to _npm_ outside of a WordPress release cycle. +The following workflow is needed when packages require bug fixes or security releases to be published to _npm_ outside of a regular WordPress release cycle. -Note: Both the `master` and `wp/trunk` branches are restricted and can only be _pushed_ to by the Gutenberg Core team. +Note: Both the `trunk` and `wp/trunk` branches are restricted and can only be _pushed_ to by the Gutenberg Core team. -Identify the commit hashes from the pull requests that need to be ported from the repo `master` branch to `wp/trunk` +Identify the commit hashes from the pull requests that need to be ported from the repo `trunk` branch to `wp/trunk` The `wp/trunk` branch now needs to be prepared to release and publish the packages to _npm_. Open a terminal and perform the following steps: -1. `git checkout master` + +1. `git checkout trunk` 2. `git pull` 3. `git checkout wp/trunk` 4. `git pull` Before porting commits check that the `wp/trunk` branch does not have any outstanding packages waiting to be published: + 1. `git checkout wp/trunk` 2. `npm run publish:check` -Now _cherry-pick_ the commits from `master` to `wp/trunk`, use `-m 1 commithash` if the commit was a pull request merge commit: +Now _cherry-pick_ the commits from `trunk` to `wp/trunk`, use `-m 1 commithash` if the commit was a pull request merge commit: + 1. `git cherry-pick -m 1 cb150a2` 2. `git push` Whilst waiting for the GitHub actions build for `wp/trunk`[branch to pass](https://github.com/WordPress/gutenberg/actions?query=branch%3Awp%2Ftrunk), identify and begin updating the `CHANGELOG.md` files: + 1. `git checkout wp/trunk` 2. `npm run publish:check` -> Example -> ```shell -> npm run publish:check -> @wordpress/e2e-tests -> @wordpress/jest-preset-default -> @wordpress/scripts -> lerna success found 3 packages ready to publish -> ``` - -Check the versions listed in the current `CHANGELOG.md` file, looking through the commit history of a package e.g [@wordpress/scripts](https://github.com/WordPress/gutenberg/commits/master/packages/scripts) and look out for _"chore(release): publish"_ and _"Update changelogs"_ commits to determine recent version bumps, then looking at the commits since the most recent release should aid with discovering what changes have occurred since the last release. + > Example + > + > ```shell + > npm run publish:check + > @wordpress/e2e-tests + > @wordpress/jest-preset-default + > @wordpress/scripts + > lerna success found 3 packages ready to publish + > ``` + +Check the versions listed in the current `CHANGELOG.md` file, looking through the commit history of a package e.g [@wordpress/scripts](https://github.com/WordPress/gutenberg/commits/HEAD/packages/scripts) and look out for _"chore(release): publish"_ and _"Update changelogs"_ commits to determine recent version bumps, then looking at the commits since the most recent release should aid with discovering what changes have occurred since the last release. Note: You may discover the current version of each package is not up to date, if so updating the previous released versions would be appreciated. -Begin updating the _changelogs_ based on the [Maintaining Changelogs](https://github.com/WordPress/gutenberg/blob/master/packages/README.md#maintaining-changelogs) documentation and commit the changes: +Begin updating the _changelogs_ based on the [Maintaining Changelogs](https://github.com/WordPress/gutenberg/blob/HEAD/packages/README.md#maintaining-changelogs) documentation and commit the changes: 1. `git checkout wp/trunk` 2. Update each of the `CHANGELOG.md` files 3. Stage the _changelog_ changes `git add packages/` 4. `git commit -m "Update changelogs"` 5. Make a note of the commit hash of this commit -> Example -> ``` -> [master 278f524f16] Update changelogs` 278f524 -> ``` + > Example + > + > ``` + > [trunk 278f524f16] Update changelogs` 278f524 + > ``` 6. `git push` Now that the changes have been committed to the `wp/trunk` branch and the Travis CI builds for the `wp/trunk` [branch are passing](https://travis-ci.com/WordPress/gutenberg/branches) it's time to publish the packages to npm: + 1. Once again run `npm run publish:check` to confirm there are no unexpected packages ready to be published: -> Example -> ```shell -> npm run publish:check -> @wordpress/e2e-tests -> @wordpress/jest-preset-default -> @wordpress/scripts -> lerna success found 3 packages ready to publish -> ``` + > Example + > + > ```shell + > npm run publish:check + > @wordpress/e2e-tests + > @wordpress/jest-preset-default + > @wordpress/scripts + > lerna success found 3 packages ready to publish + > ``` 2. Run the [package release process] but when asked for the version numbers to choose for each package use the versions you made note of above when updating each packages `CHANGELOG.md` file. -> Truncated example of publishing process output -> ``` -> npm run publish:prod -> -> Build Progress: [==============================] 100% -> lerna notice cli v3.18.2 -> lerna info versioning independent -> ? Select a new version for @wordpress/e2e-tests (currently 1.9.0) Patch (1.9.1) -> ? Select a new version for @wordpress/jest-preset-default (currently 5.3.0) Patch (5.3.1) -> ? Select a new version for @wordpress/scripts (currently 6.1.0) Patch (6.1.1) -> -> Changes: -> - @wordpress/e2e-tests: 1.9.0 => 1.9.1 -> - @wordpress/jest-preset-default: 5.3.0 => 5.3.1 -> - @wordpress/scripts: 6.1.0 => 6.1.1 -> -> ? Are you sure you want to publish these packages? Yes -> lerna info execute Skipping releases -> lerna info git Pushing tags... -> lerna info publish Publishing packages to npm... -> lerna info Verifying npm credentials -> lerna info Checking two-factor auth mode -> ? Enter OTP: 753566 -> lerna success published @wordpress/jest-preset-default 5.3.1 -> lerna success published @wordpress/scripts 6.1.1 -> lerna success published @wordpress/e2e-tests 1.9.1 -> Successfully published: -> - @wordpress/e2e-tests@1.9.1 -> - @wordpress/jest-preset-default@5.3.1 -> - @wordpress/scripts@6.1.1 -> lerna success published 3 packages -> ``` - -Now that the packages have been published the _"chore(release): publish"_ and _"Update changelogs"_ commits to `wp/trunk` need to be ported to the `master` branch: -1. `git checkout master` + > Truncated example of publishing process output + > + > ``` + > npm run publish:prod + > + > Build Progress: [==============================] 100% + > lerna notice cli v3.18.2 + > lerna info versioning independent + > ? Select a new version for @wordpress/e2e-tests (currently 1.9.0) Patch (1.9.1) + > ? Select a new version for @wordpress/jest-preset-default (currently 5.3.0) Patch (5.3.1) + > ? Select a new version for @wordpress/scripts (currently 6.1.0) Patch (6.1.1) + > + > Changes: + > - @wordpress/e2e-tests: 1.9.0 => 1.9.1 + > - @wordpress/jest-preset-default: 5.3.0 => 5.3.1 + > - @wordpress/scripts: 6.1.0 => 6.1.1 + > + > ? Are you sure you want to publish these packages? Yes + > lerna info execute Skipping releases + > lerna info git Pushing tags... + > lerna info publish Publishing packages to npm... + > lerna info Verifying npm credentials + > lerna info Checking two-factor auth mode + > ? Enter OTP: 753566 + > lerna success published @wordpress/jest-preset-default 5.3.1 + > lerna success published @wordpress/scripts 6.1.1 + > lerna success published @wordpress/e2e-tests 1.9.1 + > Successfully published: + > - @wordpress/e2e-tests@1.9.1 + > - @wordpress/jest-preset-default@5.3.1 + > - @wordpress/scripts@6.1.1 + > lerna success published 3 packages + > ``` + +Now that the packages have been published the _"chore(release): publish"_ and _"Update changelogs"_ commits to `wp/trunk` need to be ported to the `trunk` branch: + +1. `git checkout trunk` 2. `git pull` 3. Cherry-pick the `278f524`hash you noted above from the _"Update changelogs"_ commit made to `wp/trunk` 4. `git cherry-pick 278f524` 5. Get the commit hash from the the lerna publish commit either from the terminal or [wp/trunk commits](https://github.com/WordPress/gutenberg/commits/wp/trunk) -6. Cherry-pick the `fe6ae0d` "chore(release): publish"_ commit made to `wp/trunk` +6. Cherry-pick the `fe6ae0d` "chore(release): publish"\_ commit made to `wp/trunk` 7. `git cherry-pick fe6ae0d` 8. `git push` Confirm the packages dependencies do not contain `file://` links in the `dependencies` or `devdependencies` section of the packages released, e.g: -> https://unpkg.com/browse/@wordpress/jest-preset-default@5.3.1/package.json -> https://unpkg.com/browse/@wordpress/scripts@6.1.1/package.json -> https://unpkg.com/browse/@wordpress/jest-preset-default@5.3.1/package.json + +> https://unpkg.com/browse/@wordpress/jest-preset-default@5.3.1/package.json > https://unpkg.com/browse/@wordpress/scripts@6.1.1/package.json > https://unpkg.com/browse/@wordpress/jest-preset-default@5.3.1/package.json Time to announce the published changes in the #core-js and #core-editor Slack channels + > ``` > 📣 Successfully published: > • @wordpress/e2e-tests@1.9.1 @@ -409,9 +441,25 @@ Time to announce the published changes in the #core-js and #core-editor Slack ch > Lerna success published 3 packages > ``` ---------- +--- Ta-da! 🎉 +### Development Releases + +As noted in the [Synchronizing WordPress Trunk](#synchronizing-wordpress-trunk) section, the WordPress trunk branch can be closed or in "feature-freeze" mode. Usually, this happens during the WordPress ongoing release cycle, which takes several weeks. It means that packages don't get any enhancements and new features during the ongoing WordPress major release process. Another type of release is available to address the limitation mentioned earlier and unblock ongoing development for projects that depend on WordPress packages. We are taking advantage of [package distribution tags](https://docs.npmjs.com/cli/v7/commands/npm-dist-tag) that make it possible to consume the future version of the codebase according to npm guidelines: + +> By default, the `latest` tag is used by npm to identify the current version of a package, and `npm install ` (without any `@` or `@` specifier) installs the `latest` tag. Typically, projects only use the `latest` tag for stable release versions, and use other tags for unstable versions such as prereleases. + +In our case, we use the `next` distribution tag for code. Developers that want to install such a version of the package need to type: + +```bash +npm install @wordpress/components@next +``` + +The release process is fully automated via `./bin/plugin/cli.js npm-next` command. You only have to run the script, and everything else happens through interactions in the terminal. + +Behind the scenes, the `wp/next` branch is synchronized with the latest release branch (`release/*`) created for the Gutenberg plugin. To avoid collisions in the versioning of packages, we always include the newest commit's `sha`, for example, `@wordpress/block-editor@5.2.10-next.645224df70.0`. + [plugin repository]: https://plugins.trac.wordpress.org/browser/gutenberg/ -[package release process]: https://github.com/WordPress/gutenberg/blob/master/packages/README.md#releasing-packages +[package release process]: https://github.com/WordPress/gutenberg/blob/HEAD/packages/README.md#releasing-packages diff --git a/docs/contributors/scripts.md b/docs/contributors/code/scripts.md similarity index 97% rename from docs/contributors/scripts.md rename to docs/contributors/code/scripts.md index a58e18ca24df23..7efaa2a42cbdbb 100644 --- a/docs/contributors/scripts.md +++ b/docs/contributors/code/scripts.md @@ -73,7 +73,7 @@ can be excluded from the bundle and provided by WordPress in the form of script `wp_enqueue_script`)][https://developer.wordpress.org/reference/functions/wp_enqueue_script/#default-scripts-included-and-registered-by-wordpress]. The -[`@wordpress/dependency-extraction-webpack-plugin`](https://github.com/WordPress/gutenberg/tree/master/packages/dependency-extraction-webpack-plugin) +[`@wordpress/dependency-extraction-webpack-plugin`](https://github.com/WordPress/gutenberg/tree/HEAD/packages/dependency-extraction-webpack-plugin) provides a webpack plugin to help extract WordPress dependencies from bundles. `@wordpress/scripts` -[`build`](https://github.com/WordPress/gutenberg/tree/master/packages/scripts#build) script includes +[`build`](https://github.com/WordPress/gutenberg/tree/HEAD/packages/scripts#build) script includes the plugin by default. diff --git a/docs/contributors/testing-overview.md b/docs/contributors/code/testing-overview.md similarity index 96% rename from docs/contributors/testing-overview.md rename to docs/contributors/code/testing-overview.md index 7616af58afacf0..6c682fe6083bdf 100644 --- a/docs/contributors/testing-overview.md +++ b/docs/contributors/code/testing-overview.md @@ -23,7 +23,7 @@ Tests for JavaScript use [Jest](https://jestjs.io/) as the test runner and its A It should be noted that in the past, React components were unit tested with [Enzyme](https://github.com/airbnb/enzyme). However, for new tests, it is preferred to use React Testing Library (RTL) and over time old tests should be refactored to use RTL too (typically when working on code that touches an old test). -Assuming you've followed the [instructions](/docs/contributors/getting-started.md) to install Node and project dependencies, tests can be run from the command-line with NPM: +Assuming you've followed the [instructions](/docs/contributors/code/getting-started-with-code-contribution.md) to install Node and project dependencies, tests can be run from the command-line with NPM: ``` npm test @@ -31,7 +31,7 @@ npm test Linting is static code analysis used to enforce coding standards and to avoid potential errors. This project uses [ESLint](http://eslint.org/) and [TypeScript's JavaScript type-checking](https://www.typescriptlang.org/docs/handbook/type-checking-javascript-files.html) to capture these issues. While the above `npm test` will execute both unit tests and code linting, code linting can be verified independently by running `npm run lint`. Some JavaScript issues can be fixed automatically by running `npm run lint-js:fix`. -To improve your developer workflow, you should setup an editor linting integration. See the [getting started documentation](/docs/contributors/getting-started.md) for additional information. +To improve your developer workflow, you should setup an editor linting integration. See the [getting started documentation](/docs/contributors/code/getting-started-with-code-contribution.md) for additional information. To run unit tests only, without the linter, use `npm run test-unit` instead. @@ -380,13 +380,13 @@ To locally run the tests in debug mode, follow these steps: ### Native mobile end-to-end tests -Contributors to Gutenberg will note that PRs include continuous integration E2E tests running the native mobile E2E tests on Android and iOS. For troubleshooting failed tests, check our guide on [native mobile tests in continious integration](docs/contributors/native-mobile.md#native-mobile-e2e-tests-in-continuous-integration). More information on running these tests locally can be found in the [relevant directory README.md](https://github.com/WordPress/gutenberg/tree/master/packages/react-native-editor/__device-tests__). +Contributors to Gutenberg will note that PRs include continuous integration E2E tests running the native mobile E2E tests on Android and iOS. For troubleshooting failed tests, check our guide on [native mobile tests in continious integration](docs/contributors/native-mobile.md#native-mobile-e2e-tests-in-continuous-integration). More information on running these tests locally can be found in the [relevant directory README.md](https://github.com/WordPress/gutenberg/tree/HEAD/packages/react-native-editor/__device-tests__). ## End-to-end Testing End-to-end tests use [Puppeteer](https://github.com/puppeteer/puppeteer) as a headless Chromium driver, and are otherwise still run by a [Jest](https://jestjs.io/) test runner. -If you're using the built-in [local environment](/docs/contributors/getting-started.md#local-environment), you can run the e2e tests locally using this command: +If you're using the built-in [local environment](/docs/contributors/code/getting-started-with-code-contribution.md#local-environment), you can run the e2e tests locally using this command: ```bash npm run test-e2e @@ -450,11 +450,11 @@ Related: https://chromedevtools.github.io/devtools-protocol/tot/Network#method-e ### Core Block Testing -Every core block is required to have at least one set of fixture files for its main save function and one for each deprecation. These fixtures test the parsing and serialization of the block. See [the e2e tests fixtures readme](https://github.com/wordpress/gutenberg/blob/master/packages/e2e-tests/fixtures/blocks/README.md) for more information and instructions. +Every core block is required to have at least one set of fixture files for its main save function and one for each deprecation. These fixtures test the parsing and serialization of the block. See [the e2e tests fixtures readme](https://github.com/wordpress/gutenberg/blob/HEAD/packages/e2e-tests/fixtures/blocks/README.md) for more information and instructions. ## PHP Testing -Tests for PHP use [PHPUnit](https://phpunit.de/) as the testing framework. If you're using the built-in [local environment](/docs/contributors/getting-started.md#local-environment), you can run the PHP tests locally using this command: +Tests for PHP use [PHPUnit](https://phpunit.de/) as the testing framework. If you're using the built-in [local environment](/docs/contributors/code/getting-started-with-code-contribution.md#local-environment), you can run the PHP tests locally using this command: ```bash npm run test-php @@ -496,13 +496,13 @@ This gives you the result for the current branch/code on the running environment In addition to that, you can also compare the metrics across branches (or tags or commits) by running the following command `./bin/plugin/cli.js perf [branches]`, example: ``` -./bin/plugin/cli.js perf master v8.1.0 v8.0.0 +./bin/plugin/cli.js perf trunk v8.1.0 v8.0.0 ``` Finally, you can pass an additional `--tests-branch` argument to specify which branch's performance test files you'd like to run. This is particularly useful when modifying/extending the perf tests: ``` -./bin/plugin/cli.js perf master v8.1.0 v8.0.0 --tests-branch add/perf-tests-coverage +./bin/plugin/cli.js perf trunk v8.1.0 v8.0.0 --tests-branch add/perf-tests-coverage ``` **Note** This command needs may take some time to perform the benchmark. While running make sure to avoid using your computer or have a lot of background process to minimize external factors that can impact the results across branches. diff --git a/docs/contributors/design.md b/docs/contributors/design/README.md similarity index 100% rename from docs/contributors/design.md rename to docs/contributors/design/README.md diff --git a/docs/contributors/design/reference.md b/docs/contributors/design/reference.md new file mode 100644 index 00000000000000..b3d589576c7b08 --- /dev/null +++ b/docs/contributors/design/reference.md @@ -0,0 +1,18 @@ +# Reference + +- [Glossary](/docs/getting-started/glossary.md) +- [Coding Guidelines](/docs/contributors/code/coding-guidelines.md) +- [Testing Overview](/docs/contributors/code/testing-overview.md) +- [Frequently Asked Questions](/docs/getting-started/faq.md) + +## Logo + +Gutenberg Logo + +Released under GPL license, made by [Cristel Rossignol](https://twitter.com/cristelrossi). + +[Download the SVG logo](https://github.com/WordPress/gutenberg/blob/HEAD/docs/final-g-wapuu-black.svg). + +## Mockups + +Mockup Sketch files are available in [the Design section](/docs/how-to-guides/designers/design-resources.md). diff --git a/docs/contributors/the-block.md b/docs/contributors/design/the-block.md similarity index 100% rename from docs/contributors/the-block.md rename to docs/contributors/design/the-block.md diff --git a/docs/contributors/document.md b/docs/contributors/documentation/README.md similarity index 85% rename from docs/contributors/document.md rename to docs/contributors/documentation/README.md index 2845f4e8b6e0ba..e3033c3c8f88e9 100644 --- a/docs/contributors/document.md +++ b/docs/contributors/documentation/README.md @@ -25,7 +25,7 @@ The Block Editor Handbook is a mix of markdown files in the `/docs/` directory o An automated job publishes the docs every 15 minutes to the [Block Editor Handbook site](https://developer.wordpress.org/block-editor/). -See [the Git Workflow](/docs/contributors/git-workflow.md) documentation for how to use git to deploy changes using pull requests. Additionally, see the [video walk-through](https://wordpress.tv/2020/09/02/marcus-kazmierczak-contribute-developer-documentation-to-gutenberg/) and the accompanying [slides for contributing documentation to Gutenberg](https://mkaz.blog/wordpress/contribute-documentation-to-gutenberg/). +See [the Git Workflow](/docs/contributors/code/git-workflow.md) documentation for how to use git to deploy changes using pull requests. Additionally, see the [video walk-through](https://wordpress.tv/2020/09/02/marcus-kazmierczak-contribute-developer-documentation-to-gutenberg/) and the accompanying [slides for contributing documentation to Gutenberg](https://mkaz.blog/wordpress/contribute-documentation-to-gutenberg/). ### Update a Document @@ -39,11 +39,11 @@ To update an existing page: ### Create a New Document -To add a new documentation page requires a working JavaScript development environment to build the documentation, see the [JavaScript build setup documentation](/docs/designers-developer/developers/tutorials/javascript/js-build-setup.md): +To add a new documentation page requires a working JavaScript development environment to build the documentation, see the [JavaScript build setup documentation](/docs/how-to-guides/javascript/js-build-setup.md): -1. Create a Markdown file in the [docs](https://github.com/WordPress/gutenberg/tree/master/docs) folder, use lower-case, no spaces, if needed a dash separator, and .md extension. +1. Create a Markdown file in the [docs](https://github.com/WordPress/gutenberg/tree/HEAD/docs) folder, use lower-case, no spaces, if needed a dash separator, and .md extension. 2. Add content, all documents require one and only H1 tag, using markdown notation. -3. Add item to the [toc.json](https://github.com/WordPress/gutenberg/blob/master/docs/toc.json) hierarchy, see existing entries for format. +3. Add item to the [toc.json](https://github.com/WordPress/gutenberg/blob/HEAD/docs/toc.json) hierarchy, see existing entries for format. 4. Run `npm run docs:build` to update `manifest.json`. 5. Commit `manifest.json` with other files updated. @@ -67,13 +67,13 @@ This way they will be properly handled in all three aforementioned contexts. Use the full directory and filename from the Gutenberg repository, not the published path; the Block Editor Handbook creates short URLs—you can see this in the tutorials section. Likewise, the `readme.md` portion is dropped in the handbook, but should be included in links. -An example, the link to this page is: `/docs/contributors/document.md` +An example, the link to this page is: `/docs/contributors/documentation/README.md` ### Code Examples The code example in markdown should be wrapped in three tick marks \`\`\` and should additionally include a language specifier. See this [GitHub documentation around fenced code blocks](https://help.github.com/en/github/writing-on-github/creating-and-highlighting-code-blocks). -A unique feature to the Gutenberg documentation is the `codetabs` toggle, this allows two versions of code to be shown at once. This is used for showing both `ESNext` and `ES5` code samples. For example, [on this block tutorial page](/docs/designers-developers/developers/tutorials/block-tutorial/block-controls-toolbar-and-sidebar.md). +A unique feature to the Gutenberg documentation is the `codetabs` toggle, this allows two versions of code to be shown at once. This is used for showing both `ESNext` and `ES5` code samples. For example, [on this block tutorial page](/docs/how-to-guides/block-tutorial/block-controls-toolbar-and-sidebar.md). Here is an example `codetabs` section: @@ -96,7 +96,7 @@ The preferred format for code examples is ESNext, this should be the default vie ### Editor Config -You should configure your editor to use Prettier to auto-format markdown documents. See the [Getting Started documentation](/docs/contributors/develop/getting-started.md) for complete details. +You should configure your editor to use Prettier to auto-format markdown documents. See the [Getting Started documentation](/docs/contributors/code/getting-started-with-code-contribution.md) for complete details. An example config for using Visual Studio Code and the Prettier extensions: diff --git a/docs/contributors/copy-guide.md b/docs/contributors/documentation/copy-guide.md similarity index 100% rename from docs/contributors/copy-guide.md rename to docs/contributors/documentation/copy-guide.md diff --git a/docs/architecture/folder-structure.md b/docs/contributors/folder-structure.md similarity index 100% rename from docs/architecture/folder-structure.md rename to docs/contributors/folder-structure.md diff --git a/docs/contributors/outreach.md b/docs/contributors/outreach.md deleted file mode 100644 index 208a1eaf707e14..00000000000000 --- a/docs/contributors/outreach.md +++ /dev/null @@ -1,65 +0,0 @@ -# Outreach - -This includes articles, talks, demos and anything the community is doing to discuss, learn about, and contribute to Gutenberg. This is not an exhaustive list; if we are missing your event or article, just let us know. - -## Articles - -A short list of useful articles around defining, extending, and contributing to Gutenberg. - -### Overviews of Gutenberg - -- [Gutenberg, or the Ship of Theseus](https://matiasventura.com/post/gutenberg-or-the-ship-of-theseus/), Matías Ventura Bausero (October 2017) -- [We Called It Gutenberg for a Reason](https://ma.tt/2017/08/we-called-it-gutenberg-for-a-reason/), Matt Mullenweg (August 2017) -- [How Gutenberg is Changing WordPress Development](https://riad.blog/2017/10/06/how-gutenberg-is-changing-wordpress-development/), Riad Benguella (October 2017) -- [How Gutenberg Will Shape the Future of WordPress](https://www.linkedin.com/pulse/gutenberg-morten-rand-hendriksen/), Morten Rand-Henrikson (August 2017) - -### Extending Gutenberg - -- [With Gutenberg, what happens to my Custom Fields?](https://riad.blog/2017/12/11/with-gutenberg-what-happens-to-my-custom-fields/), Riad Benguella (December 2017) -- [One thousand and one ways to extend Gutenberg today](https://riad.blog/2017/10/16/one-thousand-and-one-way-to-extend-gutenberg-today/), Riad Benguella (October 2017) -- [Gutenberg Plugin Boilerplate](https://github.com/ahmadawais/Gutenberg-Boilerplate/), Ahmad Awais (August 2017) - -### Community Contribution - -- [Gutenberg Block Library](https://editorblockswp.com/library), Danny Cooper (August 2018) -- [A zero-configuration developer toolkit for building WordPress Gutenberg block plugins](https://ahmadawais.com/create-guten-block-toolkit/), Ahmad Awais (January 2018) -- [Contributing to Gutenberg Without Code](https://wordimpress.com/a-pot-stirrer-amongst-chefs-contributing-to-gutenberg-without-code/), Kevin Hoffman (August 2017) -- [Testing Flow in Gutenberg: Instructions for how to contribute to usability testing](https://make.wordpress.org/test/2017/11/22/testing-flow-in-gutenberg/), Anna Harrison (November 2017) - -### Article Compilations - -- [Curated Collection of Gutenberg Articles, Plugins, Blocks, Tutorials, etc](http://gutenberghub.com/), By Munir Kamal -- [Articles about Gutenberg](https://github.com/WordPress/gutenberg/issues/1419) (Github Issue thread with links) -- [Gutenberg articles on ManageWP.org](https://managewp.org/search?q=gutenberg) -- [Gutenberg Times](https://gutenbergtimes.com/category/updates/) - -## Talks - -Talks given about Gutenberg, including slides and videos as they are available. - -### Slides -- [The new core WordPress editor](http://kimb.me/talk-bigwp-london-new-core-wordpress-editor/) at BigWP London (18. May 2017) -- [Gutenberg Notes](http://haiku2.com/2017/09/bend-wordpress-meetup-gutenberg-notes/) at Bend WordPress Meetup (5. September 2017) -- [Gutenberg and the Future of Content in WordPress](https://www.slideshare.net/andrewmduthie/gutenberg-and-the-future-of-content-in-wordpress) (20. September 2017) -- [Head first into Gutenberg](https://speakerdeck.com/prtksxna/head-first-into-gutenberg) at the [WordPress Goa Meet-up](https://www.meetup.com/WordPressGoa/events/245275573/) (1. December 2017) -- [Gutenberg : vers une approche plus fine du contenu](https://imathi.eu/2018/02/16/gutenberg-vers-une-approche-plus-fine-du-contenu/) at [WP Paris](https://wpparis.fr/) (8. February 2018) - -### Videos -- [All `Gutenberg` tagged Talks at WordPress.tv](https://wordpress.tv/tag/gutenberg/) -- 2018-Jun - [Beyond Gutenberg](https://wordpress.tv/2018/07/09/matias-ventura-beyond-gutenberg/) by Matías Ventura -- 2018-Jun - [Anatomy of a block: Gutenberg design patterns](https://wordpress.tv/2018/07/08/tammie-lister-anatomy-of-a-block-gutenberg-design-patterns/) by Tammie Lister -- 2017-Dec - [State of the Word 2017](https://wordpress.tv/2017/12/04/matt-mullenweg-state-of-the-word-2017/) by Matt Mullenweg (Gutenberg demo by Matías Ventura at 35:00) -- [Gutenberg is Coming (Don’t Be Afraid)](https://training.ithemes.com/webinar/gutenberg-is-coming-dont-be-afraid/) from iThemes Training - -## Showcases or demonstrations: - -https://wpleeds.co.uk/events/plugins-gutenberg-wordpress-leeds-july-2017/ - -http://kimb.me/talk-bigwp-london-new-core-wordpress-editor - -https://www.facebook.com/events/278785795934302/ - -https://www.meetup.com/WordPress-Melbourne/events/241543639 - -https://wpmeetups.de/termin/29-wp-meetup-stuttgart-gutenberg-editor-rueckblick-wordcamp-europe/ - diff --git a/docs/contributors/reference.md b/docs/contributors/reference.md deleted file mode 100644 index e1e714f07940dc..00000000000000 --- a/docs/contributors/reference.md +++ /dev/null @@ -1,17 +0,0 @@ -# Reference - -- [Glossary](/docs/designers-developers/glossary.md) -- [Coding Guidelines](/docs/contributors/coding-guidelines.md) -- [Testing Overview](/docs/contributors/testing-overview.md) -- [Frequently Asked Questions](/docs/designers-developers/faq.md) - -## Logo -Gutenberg Logo - -Released under GPL license, made by [Cristel Rossignol](https://twitter.com/cristelrossi). - -[Download the SVG logo](https://github.com/WordPress/gutenberg/blob/master/docs/final-g-wapuu-black.svg). - -## Mockups - -Mockup Sketch files are available in [the Design section](/docs/designers-developers/designers/design-resources.md). diff --git a/docs/contributors/repository-management.md b/docs/contributors/repository-management.md index 609b194453b004..6ece48707c74fe 100644 --- a/docs/contributors/repository-management.md +++ b/docs/contributors/repository-management.md @@ -123,11 +123,11 @@ A pull request can generally be merged once it is: - Vetted against all potential edge cases. - Changelog entries were properly added. - Reviewed by someone other than the original author. -- [Rebased](/docs/contributors/git-workflow.md#keeping-your-branch-up-to-date) onto the latest version of the master branch. +- [Rebased](/docs/contributors/code/git-workflow.md#keeping-your-branch-up-to-date) onto the latest version of the master branch. The final pull request merge decision is made by the **@wordpress/gutenberg-core** team. -All members of the WordPress organization on GitHub have the ability to review and merge pull requests. If you have reviewed a PR and are confident in the code, approve the pull request and comment pinging **@wordpress/gutenberg-core** or a specific core member who has been involved in the PR. Once they confirm there are no objections, you are free to merge the PR into master. +All members of the WordPress organization on GitHub have the ability to review and merge pull requests. If you have reviewed a PR and are confident in the code, approve the pull request and comment pinging **@wordpress/gutenberg-core** or a specific core member who has been involved in the PR. Once they confirm there are no objections, you are free to merge the PR into trunk. Most pull requests will be automatically assigned a release milestone, but please make sure your merged pull request was assigned one. Doing so creates the historical legacy of what code landed when, and makes it possible for all project contributors (even non-technical ones) to access this information. diff --git a/docs/roadmap.md b/docs/contributors/roadmap.md similarity index 100% rename from docs/roadmap.md rename to docs/contributors/roadmap.md diff --git a/docs/contributors/triage.md b/docs/contributors/triage.md index 6da30fc5526c98..c44dc0a4b8843b 100644 --- a/docs/contributors/triage.md +++ b/docs/contributors/triage.md @@ -1,100 +1,106 @@ ### Get involved in triage + To keep the repository healthy, it needs to be triaged regularly. Triage is the practice of reviewing existing issues and pull requests to make sure they’re relevant, actionable, and have all the information they need. Anyone can help triage, although you’ll need to be a member of the triage team for the Gutenberg repository to modify an issue’s labels or edit its title. ### Join the triage team + The triage team is an open group of people with a particular role of making sure triage is done consistently across the Gutenberg repo. There are various types of triage which happen: -* Regular self triage sessions done by members on their own time. -* Organised triage sessions done as a group at a set time. You can [review the meetings page](https://make.wordpress.org/meetings/) to find these triage sessions and appropriate slack channels. -* Focused triage sessions on a specific board, label or feature. +- Regular self triage sessions done by members on their own time. +- Organised triage sessions done as a group at a set time. You can [review the meetings page](https://make.wordpress.org/meetings/) to find these triage sessions and appropriate slack channels. +- Focused triage sessions on a specific board, label or feature. These are the expectations of being a triage team member: -* You are expected to do some triage even if it is self triage at least once a week. -* As you can, try to join organized triage sessions. -* If you join the triage team to focus on a specific label or board, the expectation is that your focus will be there. Please make this known to fellow triage team members. +- You are expected to do some triage even if it is self triage at least once a week. +- As you can, try to join organized triage sessions. +- If you join the triage team to focus on a specific label or board, the expectation is that your focus will be there. Please make this known to fellow triage team members. -If you would like to join this team, simply ask in #core-editor [Slack](https://make.wordpress.org/chat/) at any time. +If you would like to join this team, simply ask in #core-editor [Slack](https://make.wordpress.org/chat/) at any time. ### Getting started -To start simply choose from one of these filtered lists below. Note: You can find most of these filters by selecting the “Sort” option from the [overall Issues page](https://github.com/wordpress/gutenberg/issues). -* All Gutenberg issues [without an assigned label](https://github.com/WordPress/gutenberg/issues?q=is%3Aopen+is%3Aissue+no%3Alabel+sort%3Aupdated-asc). Triaging by simply adding labels helps people focused on certain aspects of Gutenberg find relevant issues easier and start working on them. -* All Gutenberg pull requests [without an assigned label](https://github.com/WordPress/gutenberg/pulls?q=is%3Aopen+is%3Apr+no%3Alabel). This requires a level of comfortability with code. For more guidance on which labels are best to use, please [review this section on labeling pull requests](https://github.com/WordPress/gutenberg/blob/master/docs/contributors/repository-management.md#pull-requests) for contributors. You can also always check with the person authoring the pull request to make sure the labels match what they are intending to do. -* [The least recently updated](https://github.com/WordPress/gutenberg/issues?q=is%3Aopen+is%3Aissue+sort%3Aupdated-asc) Gutenberg issues. Triaging issues that are getting old and possibly out of date keeps important work from being overlooked. -* All Gutenberg issues [with no comments](https://github.com/wordpress/gutenberg/issues?q=is%3Aissue+is%3Aopen+comments%3A0+). Triaging this list helps make sure all issues are acknowledged, and can help identify issues that may need more information or discussion before they are actionable. -* [The least commented](https://github.com/wordpress/gutenberg/issues?q=is%3Aissue+is%3Aopen+sort%3Acomments-asc) on Gutenberg issues. Triaging this list helps the community figure out what things might still need traction for certain proposals. -* [The most commented](https://github.com/wordpress/gutenberg/issues?q=is%3Aissue+is%3Aopen+sort%3Acomments-desc) on Gutenberg issues. If you feel comfortable chiming in and the conversation has stagnated, the best way to triage these kinds of issues is to summarize the discussion thus far and do your best to identify action items, blockers, etc. Triaging this list allows finding solutions to important and complex issues to move forward. -* You can also create your own custom set of filters on GitHub. If you have a filter you think might be useful for the community, feel free to submit a PR to add it to this list. +To start simply choose from one of these filtered lists below. Note: You can find most of these filters by selecting the “Sort” option from the [overall Issues page](https://github.com/wordpress/gutenberg/issues). +- All Gutenberg issues [without an assigned label](https://github.com/WordPress/gutenberg/issues?q=is%3Aopen+is%3Aissue+no%3Alabel+sort%3Aupdated-asc). Triaging by simply adding labels helps people focused on certain aspects of Gutenberg find relevant issues easier and start working on them. +- All Gutenberg pull requests [without an assigned label](https://github.com/WordPress/gutenberg/pulls?q=is%3Aopen+is%3Apr+no%3Alabel). This requires a level of comfortability with code. For more guidance on which labels are best to use, please [review this section on labeling pull requests](/docs/contributors/repository-management.md#pull-requests) for contributors. You can also always check with the person authoring the pull request to make sure the labels match what they are intending to do. +- [The least recently updated](https://github.com/WordPress/gutenberg/issues?q=is%3Aopen+is%3Aissue+sort%3Aupdated-asc) Gutenberg issues. Triaging issues that are getting old and possibly out of date keeps important work from being overlooked. +- All Gutenberg issues [with no comments](https://github.com/wordpress/gutenberg/issues?q=is%3Aissue+is%3Aopen+comments%3A0+). Triaging this list helps make sure all issues are acknowledged, and can help identify issues that may need more information or discussion before they are actionable. +- [The least commented](https://github.com/wordpress/gutenberg/issues?q=is%3Aissue+is%3Aopen+sort%3Acomments-asc) on Gutenberg issues. Triaging this list helps the community figure out what things might still need traction for certain proposals. +- [The most commented](https://github.com/wordpress/gutenberg/issues?q=is%3Aissue+is%3Aopen+sort%3Acomments-desc) on Gutenberg issues. If you feel comfortable chiming in and the conversation has stagnated, the best way to triage these kinds of issues is to summarize the discussion thus far and do your best to identify action items, blockers, etc. Triaging this list allows finding solutions to important and complex issues to move forward. +- You can also create your own custom set of filters on GitHub. If you have a filter you think might be useful for the community, feel free to submit a PR to add it to this list. ### General triage process + When triaging, either one of the lists above or issues in general, work through issues one-by-one. Here are some steps you can perform for each issue: -* First search for duplicates. If the issue is duplicate, close it by commenting with “Duplicate of #” and add any relevant new details to the existing issue. (Don’t forget to search for duplicates among closed issues as well!). -* If the issue is missing labels, add some to better categorize it (requires proper permissions given after joining the triage team). A good starting place when adding labels is to apply one of the labels prefixed [Type] (e.g. [Type] Enhancement or [Type] Bug) to indicate what kind of issue it is. After that consider adding more descriptive labels. If the issue concerns a particular core block, add one of the labels prefixed [Block]. Or if the issue affects a particular feature there are [Feature] labels. Finally, there are labels that affect particular interest areas, like Accessibility and Internationalization. You can view all possible labels [here](https://github.com/WordPress/gutenberg/labels). -* If the title doesn’t communicate the issue clearly enough, edit it for clarity (requires proper permissions). Specifically, we’d recommend having the main feature the issue relates to in the beginning of the title ([example](https://github.com/WordPress/gutenberg/issues/6193)) and for the title to generally be as succinct yet descriptive as possible ([example](https://github.com/WordPress/gutenberg/issues/6193)). -* If it’s a bug report, test to confirm the report or add the Needs Testing label. If there is not enough information to confirm the report, add the [Status] Needs More Info label and ask for the details needed. It’s particularly beneficial when a bug report has steps for reproduction so ask the reporter to add those if they’re missing. -* Remove the [Status] Needs More Info if the author of the issue has responded with enough details. -* Close the issue with a note if it has a [Status] Needs More Info label but the author didn't respond in 2+ weeks. -* If there was a conversation on the issue but no actionable steps identified, follow up with the participants to see what’s actionable. Make sure to @ each participant when responding in a comment. -* If you feel comfortable triaging the issue further, then you can also: - * Check that the bug report is valid by debugging it to see if you can track down the technical specifics. - * Check if the issue is missing some detail and see if you can fill in those details. For instance, if a bug report is missing visual detail, it’s helpful to reproduce the issue locally and upload a screenshot or GIF. - * Consider adding the Good First Issue label if you believe this is a relatively easy issue for a first-time contributor to try to solve. - +- First search for duplicates. If the issue is duplicate, close it by commenting with “Duplicate of #” and add any relevant new details to the existing issue. (Don’t forget to search for duplicates among closed issues as well!). +- If the issue is missing labels, add some to better categorize it (requires proper permissions given after joining the triage team). A good starting place when adding labels is to apply one of the labels prefixed [Type] (e.g. [Type] Enhancement or [Type] Bug) to indicate what kind of issue it is. After that consider adding more descriptive labels. If the issue concerns a particular core block, add one of the labels prefixed [Block]. Or if the issue affects a particular feature there are [Feature] labels. Finally, there are labels that affect particular interest areas, like Accessibility and Internationalization. You can view all possible labels [here](https://github.com/WordPress/gutenberg/labels). +- If the title doesn’t communicate the issue clearly enough, edit it for clarity (requires proper permissions). Specifically, we’d recommend having the main feature the issue relates to in the beginning of the title ([example](https://github.com/WordPress/gutenberg/issues/6193)) and for the title to generally be as succinct yet descriptive as possible ([example](https://github.com/WordPress/gutenberg/issues/6193)). +- If it’s a bug report, test to confirm the report or add the Needs Testing label. If there is not enough information to confirm the report, add the [Status] Needs More Info label and ask for the details needed. It’s particularly beneficial when a bug report has steps for reproduction so ask the reporter to add those if they’re missing. +- Remove the [Status] Needs More Info if the author of the issue has responded with enough details. +- Close the issue with a note if it has a [Status] Needs More Info label but the author didn't respond in 2+ weeks. +- If there was a conversation on the issue but no actionable steps identified, follow up with the participants to see what’s actionable. Make sure to @ each participant when responding in a comment. +- If you feel comfortable triaging the issue further, then you can also: + - Check that the bug report is valid by debugging it to see if you can track down the technical specifics. + - Check if the issue is missing some detail and see if you can fill in those details. For instance, if a bug report is missing visual detail, it’s helpful to reproduce the issue locally and upload a screenshot or GIF. + - Consider adding the Good First Issue label if you believe this is a relatively easy issue for a first-time contributor to try to solve. + **Commonly Used Labels** Generally speaking, the following labels are very useful for triaging issues and will likely be the ones you use the most consistently. You can view all possible labels [here](https://github.com/WordPress/gutenberg/labels). -| Label | Reason | -| ------------- | ------------- | -|`[Type] Bug` | When an intended feature is broken. | -|`[Type] Enhancement` | When someone is suggesting an enhancement to a current feature. | -| `[Type] Help Request` | When someone is asking for general help with setup/implementation. | -| `Needs Technical Feedback` | When you see new features or API changes proposed. | -| `Needs More Info` | When it’s not clear what the issue is or it would help to provide additional details. | -| `Needs Testing` | When a new issue needs to be confirmed or old bugs seem like they are no longer relevant. | +| Label | Reason | +| -------------------------- | ----------------------------------------------------------------------------------------- | +| `[Type] Bug` | When an intended feature is broken. | +| `[Type] Enhancement` | When someone is suggesting an enhancement to a current feature. | +| `[Type] Help Request` | When someone is asking for general help with setup/implementation. | +| `Needs Technical Feedback` | When you see new features or API changes proposed. | +| `Needs More Info` | When it’s not clear what the issue is or it would help to provide additional details. | +| `Needs Testing` | When a new issue needs to be confirmed or old bugs seem like they are no longer relevant. | **Determining Priority Labels** If you have enough knowledge about the report at hand and feel confident in doing so, you can consider adding priority. Note that it’s on purpose that no priority label infers a normal level. -| Label | Reason | -| ------------- | ------------- | -|`Priority OMGWTFBBQ` | Major issues that are causing failures and are reported frequently. Typically, these are issues that are critical because they break important behavior or functionality. An example might be, “Unable to remove a block after it is added to the editor”. | -|`Priority: High` | Fits one of the current focuses and is causing a major broken experience (including flow, visual bugs and blocks). | -| `Priority: Low` | Enhancements that aren’t part of focuses, niche bugs, problems with old browsers. | +| Label | Reason | +| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `Priority OMGWTFBBQ` | Major issues that are causing failures and are reported frequently. Typically, these are issues that are critical because they break important behavior or functionality. An example might be, “Unable to remove a block after it is added to the editor”. | +| `Priority: High` | Fits one of the current focuses and is causing a major broken experience (including flow, visual bugs and blocks). | +| `Priority: Low` | Enhancements that aren’t part of focuses, niche bugs, problems with old browsers. | ### Closing issues -Issues are closed for the following reasons: +Issues are closed for the following reasons: -* A PR and/or latest release resolved the reported issue. -* Duplicate of a current report. -* Help request that is best handled in the WordPress.org forums. -* An issue that's not able to be replicated. -* An issue that needs more information that the author of the issue hasn't responded to for 2+ weeks. -* An item that is determined as unable to be fixed or is working as intended. +- A PR and/or latest release resolved the reported issue. +- Duplicate of a current report. +- Help request that is best handled in the WordPress.org forums. +- An issue that's not able to be replicated. +- An issue that needs more information that the author of the issue hasn't responded to for 2+ weeks. +- An item that is determined as unable to be fixed or is working as intended. ### Release specific triage + Here are some guidelines to follow when doing triage specifically around the time of a release. This is important to differentiate compared to general triage so problematic, release blocking bugs are properly identified and solutions are found. -* If a bug is introduced in a release candidate (RC) and it's going to break many workflows, add it to the version milestone and flag in the #core-editor channel in WordPress.org slack. -* If a bug was introduced in the most recent version, and a next RC hasn’t yet happened, ideally the developers can push to fix it prior to RC! The amount of push for a fix should scale proportional to the potential of breakage. In this case, add to the RC milestone and, if deemed urgent, ping in the #core-editor channel in WordPress.org slack. -* If a bug wasn’t introduced in the most recent version, do not add a milestone. Instead, use labels like “[Priority] High” if it’s a pressing issue, and if needed you can call attention to it in the weekly core meetings. +- If a bug is introduced in a release candidate (RC) and it's going to break many workflows, add it to the version milestone and flag in the #core-editor channel in WordPress.org slack. +- If a bug was introduced in the most recent version, and a next RC hasn’t yet happened, ideally the developers can push to fix it prior to RC! The amount of push for a fix should scale proportional to the potential of breakage. In this case, add to the RC milestone and, if deemed urgent, ping in the #core-editor channel in WordPress.org slack. +- If a bug wasn’t introduced in the most recent version, do not add a milestone. Instead, use labels like “[Priority] High” if it’s a pressing issue, and if needed you can call attention to it in the weekly core meetings. ### Design specific triage -Along with the general triage flows listed previously, there are some specific additions to the flows for more design-centric triage for design minded folks participating in triage. - -* PR testing and reviews: this should be your first stop for daily self triage. -* Needs design feedback: check if the issue does need design feedback and, if possible, give it. You can organize this by priority, project boards or by least commented. Once there are enough opinions, please remove this label and decide on next steps (ie adding the Needs Design label). -* Needs design: Does it really need a design? Does this fit a focus? If it has a design mark as ‘needs design feedback’ to better categorize the issue. - -Reminders: -* Ask for screenshots as needed. -* Ask for iterations and note any changes before merging. -* If the issue isn’t in a board, check to see if it doesn’t fit in a specific focus. -* If the issue/pull has not been prioritized yet, consider adding a priority label to help move the issue forward. - -For more detailed information about weekly design triage and to join in, please [review this guide](https://make.wordpress.org/design/handbook/workflows/weekly-gutenberg-design-triage/). + +Along with the general triage flows listed previously, there are some specific additions to the flows for more design-centric triage for design minded folks participating in triage. + +- PR testing and reviews: this should be your first stop for daily self triage. +- Needs design feedback: check if the issue does need design feedback and, if possible, give it. You can organize this by priority, project boards or by least commented. Once there are enough opinions, please remove this label and decide on next steps (ie adding the Needs Design label). +- Needs design: Does it really need a design? Does this fit a focus? If it has a design mark as ‘needs design feedback’ to better categorize the issue. + +Reminders: + +- Ask for screenshots as needed. +- Ask for iterations and note any changes before merging. +- If the issue isn’t in a board, check to see if it doesn’t fit in a specific focus. +- If the issue/pull has not been prioritized yet, consider adding a priority label to help move the issue forward. + +For more detailed information about weekly design triage and to join in, please [review this guide](https://make.wordpress.org/design/handbook/workflows/weekly-gutenberg-design-triage/). diff --git a/docs/contributors/versions-in-wordpress.md b/docs/contributors/versions-in-wordpress.md index 90069db6af9794..32a2a83971b737 100644 --- a/docs/contributors/versions-in-wordpress.md +++ b/docs/contributors/versions-in-wordpress.md @@ -1,12 +1,14 @@ # Versions in WordPress -With each major release of WordPress a new version of Gutenberg is included. This has caused confusion over time as people have tried to figure out how to best debug problems and report bugs appropriately. To make this easier we have made this document to serve as a canonical list of the Gutenberg versions integrated into each major WordPress release. Of note, during the beta period of a WordPress release, additional bug fixes from later Gutenberg releases than those noted are added into the WordPress release where it is needed. +With each major release of WordPress a new version of Gutenberg is included. This has caused confusion over time as people have tried to figure out how to best debug problems and report bugs appropriately. To make this easier we have made this document to serve as a canonical list of the Gutenberg versions integrated into each major WordPress release. Of note, during the beta period of a WordPress release, additional bug fixes from later Gutenberg releases than those noted are added into the WordPress release where it is needed. If you want details about what's in each Gutenberg release outside of the high level items shared as part of major WordPress releases, please review the [release notes shared on Make Core](https://make.wordpress.org/core/tag/gutenberg-new/). If anything looks incorrect here, please bring it up in #core-editor in [WordPress.org slack](https://make.wordpress.org/chat/). | Gutenberg Versions | WordPress Version | | ------------------ | ----------------- | -| 8.6-9.2 | 5.6 | +| 9.3-9.9 | 5.7 | +| 8.6-9.2 | 5.6.1 | +| 8.6-9.2 | 5.6 | | 7.6-8.5 | 5.5.3 | | 7.6-8.5 | 5.5.2 | | 7.6-8.5 | 5.5.1 | diff --git a/docs/designers-developers/developers/block-api/README.md b/docs/designers-developers/developers/block-api/README.md deleted file mode 100644 index dd8c6468882935..00000000000000 --- a/docs/designers-developers/developers/block-api/README.md +++ /dev/null @@ -1,15 +0,0 @@ -# Block API Reference - -Blocks are the fundamental element of the editor. They are the primary way in which plugins and themes can register their own functionality and extend the capabilities of the editor. - -The following sections will walk you through the existing block APIs: - -- [Block registration](/docs/designers-developers/developers/block-api/block-registration.md) -- [Edit and Save](/docs/designers-developers/developers/block-api/block-edit-save.md) -- [Attributes](/docs/designers-developers/developers/block-api/block-attributes.md) -- [Deprecated blocks](/docs/designers-developers/developers/block-api/block-deprecation.md) -- [Supports](/docs/designers-developers/developers/block-api/block-supports.md) -- [Transformations](/docs/designers-developers/developers/block-api/block-transforms.md) -- [Templates](/docs/designers-developers/developers/block-api/block-templates.md) -- [Annotations](/docs/designers-developers/developers/block-api/block-annotations.md) -- [Block Patterns](/docs/designers-developers/developers/block-api/block-patterns.md) diff --git a/docs/designers-developers/developers/data/README.md b/docs/designers-developers/developers/data/README.md deleted file mode 100644 index 7408d171144cf4..00000000000000 --- a/docs/designers-developers/developers/data/README.md +++ /dev/null @@ -1,11 +0,0 @@ -# Data Module Reference - - - [**core**: WordPress Core Data](/docs/designers-developers/developers/data/data-core.md) - - [**core/annotations**: Annotations](/docs/designers-developers/developers/data/data-core-annotations.md) - - [**core/blocks**: Block Types Data](/docs/designers-developers/developers/data/data-core-blocks.md) - - [**core/block-editor**: The Block Editor’s Data](/docs/designers-developers/developers/data/data-core-block-editor.md) - - [**core/editor**: The Post Editor’s Data](/docs/designers-developers/developers/data/data-core-editor.md) - - [**core/edit-post**: The Editor’s UI Data](/docs/designers-developers/developers/data/data-core-edit-post.md) - - [**core/notices**: Notices Data](/docs/designers-developers/developers/data/data-core-notices.md) - - [**core/nux**: The NUX (New User Experience) Data](/docs/designers-developers/developers/data/data-core-nux.md) - - [**core/viewport**: The Viewport Data](/docs/designers-developers/developers/data/data-core-viewport.md) \ No newline at end of file diff --git a/docs/designers-developers/developers/themes/theme-json.md b/docs/designers-developers/developers/themes/theme-json.md deleted file mode 100644 index b66cd3d621439c..00000000000000 --- a/docs/designers-developers/developers/themes/theme-json.md +++ /dev/null @@ -1,374 +0,0 @@ -# Themes & Block Editor: experimental theme.json - -> **These features are still experimental**. “Experimental” means this is an early implementation subject to drastic and breaking changes. -> -> Documentation has been shared early to surface what’s being worked on and invite feedback from those experimenting with the APIs. Please, be welcome to share yours in the weekly #core-editor chats as well as async via the Github issues and Pull Requests. - -This is documentation for the current direction and work in progress about how themes can hook into the various sub-systems that the Block Editor provides. - -- Rationale - - Settings can be controlled per block - - CSS Custom Properties: presets & custom - - Some block styles are managed -- Specification - - Settings - - Styles - -## Rationale - -The Block Editor surface API has evolved at different velocities, and it's now at a point where is showing some growing pains, specially in areas that affect themes. Examples of this are: the ability to [control the editor programmatically](https://make.wordpress.org/core/2020/01/23/controlling-the-block-editor/), or [a block style system](https://github.com/WordPress/gutenberg/issues/9534) that facilitates user, theme, and core style preferences. - -This describes the current efforts to consolidate the various APIs into a single point – a `experimental-theme.json` file that should be located inside the root of the theme directory. - -### Settings can be controlled per block - -The Block Editor already allows the control of specific settings such as alignment, drop cap, whether it's present in the inserter, etc at the block level. The goal is to surface these for themes to control at a block level. - -### CSS Custom Properties - -Presets such as [color palettes](https://developer.wordpress.org/block-editor/developers/themes/theme-support/#block-color-palettes), [font sizes](https://developer.wordpress.org/block-editor/developers/themes/theme-support/#block-font-sizes), and [gradients](https://developer.wordpress.org/block-editor/developers/themes/theme-support/#block-gradient-presets) become CSS Custom Properties, and will be enqueued by the system for themes to use in both the front-end and the editors. There's also a mechanism to create your own CSS Custom Properties. - -### Some block styles are managed - -By providing the block style properties in a structured way, the Block Editor can "manage" the CSS that comes from different origins (user, theme, and core CSS), reducing the amount of CSS loaded in the page and preventing specificity wars due to the competing needs of the components involved (themes, blocks, plugins). - -## Specification - -The `experimental-theme.json` file is divided into sections known as "contexts", that represent a different CSS selector. For example, the `core/paragraph` context maps to `p` while `core/group` maps to `.wp-block-group`. In general, one block will map to a single context as in the cases mentioned. There are cases where one block can generate multiple contexts (different CSS selectors). For example, the heading block generates six different contexts (`core/heading/h1`, `core/heading/h2`, etc), one for each different selector (h1, h2, etc). - -``` -{ - "global": { ... }, - "core/paragraph": { ... }, - "core/group": { ... }, - "core/heading/h1": { ... }, - "core/heading/h2": { ... }, - "core/heading/h3": { ... }, - "core/heading/h4": { ... }, - "core/heading/h5": { ... }, - "core/heading/h6": { ... } -} -``` - -Every context has the same structure, divided in two sections: `settings` and `styles`. The `settings` are used to control the editor (enable/disable certain features, declare presets), taking over what was previously declared via `add_theme_support`. The `styles` will be used to create new style rules to be appended to a new stylesheet `global-styles-inline-css` enqueued in the front-end and post editor. - -``` -{ - "some/context": { - "settings": { - "color": [ ... ], - "custom": [ ... ], - "spacing": [ ... ], - "typography": [ ... ] - }, - "styles": { - "color": { ... }, - "typography": { ... } - } - } -} -``` - -This structure is the same for the three different origins that exist: core, themes, and users. Themes can override core's defaults by creating a file called `experimental-theme.json`. Users, via the site editor, will also be also to override theme's or core's preferences via an user interface that is being worked on. - -### Settings - -The settings section has the following structure and default values: - -``` -{ - "some/context": { - "settings": { - "color": { - "custom": true, /* false to opt-out, as in add_theme_support('disable-custom-colors') */ - "customGradient": true, /* false to opt-out, as in add_theme_support('disable-custom-gradients') */ - "gradients": [ ... ], /* gradient presets, as in add_theme_support('editor-gradient-presets', ... ) */ - "link": false, /* true to opt-in, as in add_theme_support('experimental-link-color') */ - "palette": [ ... ], /* color presets, as in add_theme_support('editor-color-palette', ... ) */ - }, - "custom": { ... }, - "spacing": { - "customPadding": false, /* true to opt-in, as in add_theme_support('custom-spacing') */ - "units": [ "px", "em", "rem", "vh", "vw" ], /* filter values, as in add_theme_support('custom-units', ... ) */ - }, - "typography": { - "customFontSize": true, /* false to opt-out, as in add_theme_support( 'disable-custom-font-sizes' ) */ - "customFontWeight": true, /* false to opt-out */ - "customFontStyle": true, /* false to opt-out */ - "customLineHeight": false, /* true to opt-in, as in add_theme_support( 'custom-line-height' ) */ - "dropCap": true, /* false to opt-out */ - "fontFamilies": [ ... ], /* font family presets */ - "fontSizes": [ ... ], /* font size presets, as in add_theme_support('editor-font-sizes', ... ) */ - "fontStyles": [ ... ], /* font style presets */ - "fontWeights": [ ... ], /* font weight presets */ - "textDecorations": [ ... ], /* text decoration presets */ - "textTransforms": [ ... ] /* text transform presets */ - } - } - } -} -``` - -To retain backward compatibility, `add_theme_support` declarations are retrofit in the proper categories. If a theme uses `add_theme_support('disable-custom-colors')`, it'll be the same as set `global.settings.color.custom` to `false`. If the `experimental-theme.json` contains any settings, these will take precedence over the values declared via `add_theme_support`. - -Settings can also be controlled by context, providing a more fine-grained control over what exists via `add_theme_support`. As an example, let's say that a theme author wants to enable custom colors for the paragraph block exclusively. This is how it'd be done: - -```json -{ - "global": { - "settings": { - "color": { - "custom": false - } - } - }, - "core/paragraph": { - "settings": { - "color": { - "custom": true - } - } - } -``` - -Note, however, that not all settings are relevant for all contexts and the blocks they represent. The settings section provides an opt-in/opt-out mechanism for themes, but it's the block's responsibility to add support for the features that are relevant to it. For example, if a block doesn't implement the `dropCap` feature, a theme can't enable it for such a block through `experimental-theme.json`. - -#### Presets - -Presets are part of the settings section. At the moment, they only work within the `global` context. Each preset value will generate a CSS Custom Property that will be added to the new stylesheet, which follow this naming schema: `--wp--preset--{preset-category}--{preset-slug}`. - -For example, for this input: - -```json -{ - "global": { - "settings": { - "color": { - "palette": [ - { - "slug": "strong-magenta", - "color": "#a156b4" - }, - { - "slug": "very-dark-grey", - "color": "rgb(131, 12, 8)" - } - ], - "gradients": [ - { - "slug": "blush-bordeaux", - "gradient": "linear-gradient(135deg,rgb(254,205,165) 0%,rgb(254,45,45) 50%,rgb(107,0,62) 100%)" - }, - { - "slug": "blush-light-purple", - "gradient": "linear-gradient(135deg,rgb(255,206,236) 0%,rgb(152,150,240) 100%)" - }, - ] - }, - "typography": { - "fontSizes": [ - { - "slug": "normal", - "size": 16 - }, - { - "slug": "big", - "size": 32 - } - ] - } - } - } -} -``` - -The output to be enqueued will be: - -```css -:root { - --wp--preset--color--strong-magenta: #a156b4; - --wp--preset--color--very-dark-gray: #444; - --wp--preset--font-size--big: 32; - --wp--preset--font-size--normal: 16; - --wp--preset--gradient--blush-bordeaux: linear-gradient(135deg,rgb(254,205,165) 0%,rgb(254,45,45) 50%,rgb(107,0,62) 100%); - --wp--preset--gradient--blush-light-purple: linear-gradient(135deg,rgb(255,206,236) 0%,rgb(152,150,240) 100%); -} -``` - -The goal is that presets can be defined using this format, although, right now, the name property (used in the editor) can't be translated from this file. For that reason, and to maintain backward compatibility, the presets declared via `add_theme_support` will also generate the CSS Custom Properties. If the `experimental-theme.json` contains any presets, these will take precedence over the ones declared via `add_theme_support`. - -#### Free-form CSS Custom Properties - -In addition to create CSS Custom Properties for the presets, the theme.json also allows for themes to create their own, so they don't have to be enqueued separately. Any values declared within the `settings.custom` section will be transformed to CSS Custom Properties following this naming schema: `--wp--custom--`. - -For example, for this input: - -```json -{ - "global": { - "settings": { - "custom": { - "base-font": 16, - "line-height": { - "small": 1.2, - "medium": 1.4, - "large": 1.8 - } - } - } - } -} -``` - -The output will be: - -```css -:root { - --wp--custom--base-font: 16; - --wp--custom--line-height--small: 1.2; - --wp--custom--line-height--medium: 1.4; - --wp--custom--line-height--large: 1.8; -} -``` - -Note that, the name of the variable is created by adding `--` in between each nesting level. - -### Styles - -Each block declares which style properties it exposes. This has been coined as "implicit style attributes" of the block. These properties are then used to automatically generate the UI controls for the block in the editor, as well as being available through the `experimental-theme.json` file for themes to target. - -```json -{ - "some/context": { - "styles": { - "color": { - "background": "value", - "gradient": "value", - "link": "value", - "text": "value" - }, - "spacing": { - "padding": { - "top": "value", - "right": "value", - "bottom": "value", - "left": "value", - }, - }, - "typography": { - "fontFamily": "value", - "fontSize": "value", - "fontStyle": "value", - "fontWeight": "value", - "lineHeight": "value", - "textDecoration": "value", - "textTransform": "value" - } - } - } -} -``` - -For example, an input like this: - -```json -{ - "core/heading/h1": { - "styles": { - "color": { - "text": "var(--wp--preset--color--primary)" - }, - "typography": { - "fontSize": "calc(1px * var(--wp--preset--font-size--huge))" - } - } - }, - "core/heading/h4": { - "styles": { - "color": { - "text": "var(--wp--preset--color--secondary)" - }, - "typography": { - "fontSize": "var(--wp--preset--font-size--normal)" - } - } - } -} -``` - -will append the following style rules to the stylesheet: - -```css -h1 { - color: var(--wp--preset--color--primary); - font-size: calc(1px * var(--wp--preset--font-size--huge)); -} -h4 { - color: var(--wp--preset--color--secondary); - font-size: calc(1px * var(--wp--preset--font-size--normal)); -} -``` - -#### Color Properties - -These are the current color properties supported by blocks: - -| Context | Background | Gradient | Link | Text | -| --- | --- | --- | --- | --- | -| Global | Yes | Yes | Yes | Yes | -| Columns | Yes | Yes | Yes | Yes | -| Group | Yes | Yes | Yes | Yes | -| Heading [1] | Yes | - | Yes | Yes | -| List | Yes | Yes | - | Yes | -| Media & text | Yes | Yes | Yes | Yes | -| Navigation | Yes | - | - | Yes | -| Paragraph | Yes | - | Yes | Yes | -| Post Author | Yes | Yes | Yes | Yes | -| Post Comments | Yes | Yes | Yes | Yes | -| Post Comments Count | Yes | Yes | - | Yes | -| Post Comments Form | Yes | Yes | Yes | Yes | -| Post Date | Yes | Yes | - | Yes | -| Post Excerpt | Yes | Yes | Yes | Yes | -| Post Hierarchical Terms | Yes | Yes | Yes | Yes | -| Post Tags | Yes | Yes | Yes | Yes | -| Post Title | Yes | Yes | - | Yes | -| Site Tagline | Yes | Yes | - | Yes | -| Site Title | Yes | Yes | - | Yes | -| Template Part | Yes | Yes | Yes | Yes | - -[1] The heading block represents 6 distinct HTML elements: H1-H6. It comes with selectors to target each individual element (ex: core/heading/h1 for H1, etc). - -#### Spacing Properties - -| Context | Padding | -| --- | --- | -| Cover | Yes | -| Group | Yes | - -#### Typography Properties - -These are the current typography properties supported by blocks: - -| Context | Font Family | Font Size | Font Style | Font Weight | Line Height | Text Decoration | Text Transform | -| --- | --- | --- | --- | --- | --- | --- | --- | -| Global | Yes | Yes | Yes | Yes | Yes | Yes | Yes | -| Code | - | Yes | - | - | - | - | - | -| Heading [1] | - | Yes | - | - | Yes | - | - | -| List | - | Yes | - | - | - | - | - | -| Navigation | Yes | Yes | Yes | Yes | - | Yes | Yes | -| Paragraph | - | Yes | - | - | Yes | - | - | -| Post Author | - | Yes | - | - | Yes | - | - | -| Post Comments | - | Yes | - | - | Yes | - | - | -| Post Comments Count | - | Yes | - | - | Yes | - | - | -| Post Comments Form | - | Yes | - | - | Yes | - | - | -| Post Date | - | Yes | - | - | Yes | - | - | -| Post Excerpt | - | Yes | - | - | Yes | - | - | -| Post Hierarchical Terms | - | Yes | - | - | Yes | - | - | -| Post Tags | - | Yes | - | - | Yes | - | - | -| Post Title | Yes | Yes | - | - | Yes | - | - | -| Preformatted | - | Yes | - | - | - | - | - | -| Site Tagline | Yes | Yes | - | - | Yes | - | - | -| Site Title | Yes | Yes | - | - | Yes | - | - | -| Verse | Yes | Yes | - | - | - | - | - | - -[1] The heading block represents 6 distinct HTML elements: H1-H6. It comes with selectors to target each individual element (ex: core/heading/h1 for H1, etc). diff --git a/docs/designers-developers/developers/tutorials/metabox/meta-block-1-intro.md b/docs/designers-developers/developers/tutorials/metabox/meta-block-1-intro.md deleted file mode 100644 index ce001938ecfa68..00000000000000 --- a/docs/designers-developers/developers/tutorials/metabox/meta-block-1-intro.md +++ /dev/null @@ -1,17 +0,0 @@ -# Store Post Meta with a Block - -Typically, blocks store their attribute values in the serialised block HTML. However, you can also create a block that saves its attribute values as post meta, which can be accessed programmatically anywhere in your template. - -In this short tutorial you will create one of these blocks, which will prompt a user for a single value, and save it as post meta. - -For background around the thinking of blocks as the interface, please see the [key concepts section](/docs/architecture/key-concepts.md) of the handbook. - -Before starting this tutorial, you will need a plugin to hold your code. Please take a look at the first two steps of [the JavaScript tutorial](/docs/designers-developers/developers/tutorials/javascript/readme.md) for information setting up a plugin. - -## Table of Contents - -1. [Register Meta Field](/docs/designers-developers/developers/tutorials/metabox/meta-block-2-register-meta.md) -2. [Add Meta Block](/docs/designers-developers/developers/tutorials/metabox/meta-block-3-add.md) -3. [Use Post Meta Data](/docs/designers-developers/developers/tutorials/metabox/meta-block-4-use-data.md) -4. [Finishing Touches](/docs/designers-developers/developers/tutorials/metabox/meta-block-5-finishing.md) - diff --git a/docs/designers-developers/developers/tutorials/readme.md b/docs/designers-developers/developers/tutorials/readme.md deleted file mode 100644 index 17c428bbb508b0..00000000000000 --- a/docs/designers-developers/developers/tutorials/readme.md +++ /dev/null @@ -1,19 +0,0 @@ -# Tutorials - -- First things first, see [setting up your development environment](/docs/designers-developers/developers/tutorials/devenv/readme.md) for the tools and setup you need to extend the block editor. - -- See the [Getting Started with JavaScript Tutorial](/docs/designers-developers/developers/tutorials/javascript/readme.md) to learn about how to use JavaScript within WordPress. - -- Beginners: The [Create a Block Tutorial](/docs/designers-developers/developers/tutorials/create-block/readme.md) walks through creating a block plugin using the `@wordpress/create-block` package; a quick and easy way to start creating your own block. - -- Intermediate: The [Block Tutorial](/docs/designers-developers/developers/tutorials/block-tutorial/readme.md) covers different aspects of block development. The documentation is slightly dated but still valid, if you are new to block development, start with the Create Block Tutorial above. - -- See the [Meta Boxes Tutorial](/docs/designers-developers/developers/tutorials/metabox/readme.md) for new ways of extending the editor storing and using post meta data. - -- Check out the [Notices Tutorial](/docs/designers-developers/developers/tutorials/notices/README.md) to learn how to display informational UI at the top of the editor. - -- The [Sidebar Tutorial](/docs/designers-developers/developers/tutorials/sidebar-tutorial/plugin-sidebar-0.md) will walk you through the steps of creating a sidebar to update data from the `post_meta` table. - -- Learn how to add customized buttons to the toolbar with the [Format API tutorial](/docs/designers-developers/developers/tutorials/format-api/). - -- Build your own [custom block editor instance](/docs/designers-developers/developers/platform/custom-block-editor/) - this will walk you through building a standalone instance of the block editor within WP Admin. diff --git a/docs/designers-developers/developers/tutorials/sidebar-tutorial/plugin-sidebar-0.md b/docs/designers-developers/developers/tutorials/sidebar-tutorial/plugin-sidebar-0.md deleted file mode 100644 index f5f270cc9c5330..00000000000000 --- a/docs/designers-developers/developers/tutorials/sidebar-tutorial/plugin-sidebar-0.md +++ /dev/null @@ -1,12 +0,0 @@ -# Creating a Sidebar for Your Plugin - -This tutorial starts with you having an existing plugin setup and ready to add PHP and JavaScript code. Please, refer to [Getting started with JavaScript](/docs/designers-developers/developers/tutorials/javascript/) tutorial for an introduction to WordPress plugins and how to use JavaScript to extend the block editor. - - In the next sections, you're going to create a custom sidebar for a plugin that contains a text control so the user can update a value that is stored in the `post_meta` table. - -1. [Get a sidebar up and running](/docs/designers-developers/developers/tutorials/sidebar-tutorial/plugin-sidebar-1-up-and-running.md) -2. [Tweak the sidebar style and add controls](/docs/designers-developers/developers/tutorials/sidebar-tutorial/plugin-sidebar-2-styles-and-controls.md) -3. [Register a new meta field](/docs/designers-developers/developers/tutorials/sidebar-tutorial/plugin-sidebar-3-register-meta.md) -4. [Initialize the input control with the meta field value](/docs/designers-developers/developers/tutorials/sidebar-tutorial/plugin-sidebar-4-initialize-input.md) -5. [Update the meta field value when input's content changes](/docs/designers-developers/developers/tutorials/sidebar-tutorial/plugin-sidebar-5-update-meta.md) -6. [Finishing touches](/docs/designers-developers/developers/tutorials/sidebar-tutorial/plugin-sidebar-6-finishing-touches.md) diff --git a/docs/explanations/README.md b/docs/explanations/README.md new file mode 100644 index 00000000000000..04d9f8e9e15b52 --- /dev/null +++ b/docs/explanations/README.md @@ -0,0 +1,12 @@ +# Explanations + +## [Architecture](/docs/explanations/architecture/README.md) + +- [Key Concepts](/docs/explanations/architecture/key-concepts.md) +- [Data Format And Data Flow](/docs/explanations/architecture/data-flow.md) +- [Modularity and WordPress Packages](/docs/explanations/architecture/modularity.md). +- [Block Editor Performance](/docs/explanations/architecture/performance.md). +- What are the decision decisions behind the Data Module? +- [Why is Puppeteer the tool of choice for end-to-end tests?](/docs/explanations/architecture/automated-testing.md) +- [What’s the difference between the different editor packages? What’s the purpose of each package?](/docs/explanations/architecture/modularity.md/#whats-the-difference-between-the-different-editor-packages-whats-the-purpose-of-each-package) +- [Template and template parts flows](/docs/explanations/architecture/full-site-editing-templates.md) diff --git a/docs/explanations/architecture/README.md b/docs/explanations/architecture/README.md new file mode 100644 index 00000000000000..3ae16794dfa4ff --- /dev/null +++ b/docs/explanations/architecture/README.md @@ -0,0 +1,13 @@ +# Architecture + +Let’s look at the big picture and the architectural and UX principles of the block editor and the Gutenberg repository. + +- [Key Concepts](/docs/explanations/architecture/key-concepts.md) +- [Data Format And Data Flow](/docs/explanations/architecture/data-flow.md) +- [Understand the repository folder structure](/docs/contributors/folder-structure.md). +- [Modularity and WordPress Packages](/docs/explanations/architecture/modularity.md). +- [Block Editor Performance](/docs/explanations/architecture/performance.md). +- What are the decision decisions behind the Data Module? +- [Why is Puppeteer the tool of choice for end-to-end tests?](/docs/explanations/architecture/automated-testing.md) +- [What's the difference between the different editor packages? What's the purpose of each package?](/docs/explanations/architecture/modularity.md#whats-the-difference-between-the-different-editor-packages-whats-the-purpose-of-each-package) +- [Template and template parts flows](/docs/explanations/architecture/fse-templates.md) diff --git a/docs/explanations/architecture/automated-testing.md b/docs/explanations/architecture/automated-testing.md new file mode 100644 index 00000000000000..42dfd28a571b0f --- /dev/null +++ b/docs/explanations/architecture/automated-testing.md @@ -0,0 +1,20 @@ +# Automated Testing + +## Why is Puppeteer the tool of choice for end-to-end tests? + +There exists a rich ecosystem of tooling available for web-based end-to-end automated testing. Thus, it's a common question: "Why does Gutenberg use [Puppeteer](https://developers.google.com/web/tools/puppeteer/) instead of ([Cypress](https://cypress.io/), [Selenium](https://www.selenium.dev/), [Playwright](https://github.com/microsoft/playwright), etc)?". Given some historical unreliability of the build results associated with end-to-end tests, it's especially natural to weigh this question in considering whether our tools are providing more value than the effort required in maintaining them. While we should always be comfortable in reevaluating earlier decisions, there were and continue to be many reasons that Puppeteer is the best compromise of the options available for end-to-end testing. + +These include: + +- **Interoperability with existing testing framework**. Puppeteer is "just" a tool for controlling a Chrome browser, and makes no assumptions about how it's integrated into a testing environment. While this requires some additional effort in ensuring the test environment is available, it also allows for cohesion in how it integrates with an existing setup. Gutenberg is able to consistently use Jest for both unit testing and end-to-end testing. This is contrasted with other solutions like Cypress, which provide their own testing framework and assertion library as part of an all-in-one solution. +- **An expressive but predictable API**. Puppeteer strikes a nice balance between low-level access to browser behavior, while retaining an expressive API for issuing and awaiting responses to those commands using modern JavaScript [`async` and `await` syntax](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Asynchronous/Async_await). This is contrasted with other solutions, which either don't support or leverage native language async functionality, don't expose direct access to the browser, or leverage custom domain-specific language syntaxes for expressing browser commands and assertions. The fact that Puppeteer largely targets the Chrome browser is non-ideal in how it does not provide full browser coverage. On the other hand, the limited set of browser targets offers more consistent results and stronger guarantees about how code is evaluated in the browser environment. +- **Surfacing bugs, not obscuring them**. Many alternative solutions offer options to automatically await settled network requests or asynchronous appearance of elements on the page. While this can serve as a convenience in accounting for unpredictable delays, it can also unknowingly cause oversight of legitimate user-facing issues. For example, if an element will only appear on the page after some network request or computation has completed, it may be easy to overlook that these delays can cause unpredictable and frustrating behavior for users ([example](https://github.com/WordPress/gutenberg/pull/11287)). Given that developers often test on high-end hardware and stable network connections, consideration of resiliency on low-end hardware or spotty network availability is not always on the forefront of one's considerations. Puppeteer forces us to acknowledge these delays with explicit `waitFor*` expressions, putting us in much greater alignment with the real-world experience of an end-user. +- **Debugging**. It's important that in that case that a test fails, there should be straight-forward means to diagnose and resolve the issue. While its offerings are rather simplistic relative to the competition, Puppeteer does expose options to run tests as "headful" (with the browser visible) and with delayed actions. Combined with the fact that it interoperates well with native language / runtime features (e.g. debugger statements or breakpoints), this provides developers with sufficient debugging access. + +For more context, refer to the following resources: + +- [Testing Overview: End-to-End Testing](/docs/contributors/code/testing-overview.md#end-to-end-testing) +- [Testing: Experiment with Puppeteer for E2E testing](https://github.com/WordPress/gutenberg/pull/5618) + - In early iterations, the contributing team opted to use Cypress for end-to-end testing. This pull request outlines problems with the approach, and proposed the initial transition to Puppeteer. +- [JavaScript Chat Summary: January 28, 2020](https://make.wordpress.org/core/2020/02/04/javascript-chat-summary-january-28-2020/) + - Playwright is a new offering created by many of the original contributors to Puppeteer. It offers increased browser coverage and improved reliability of tests. While still early in development at the time of this writing, there has been some interest in evaluating it for future use as an end-to-end testing solution. diff --git a/docs/architecture/data-flow.md b/docs/explanations/architecture/data-flow.md similarity index 98% rename from docs/architecture/data-flow.md rename to docs/explanations/architecture/data-flow.md index 3fefec3aae7e77..07957382ec1bf2 100644 --- a/docs/architecture/data-flow.md +++ b/docs/explanations/architecture/data-flow.md @@ -104,7 +104,7 @@ After running this through the parser, we're left with a simple object we can ma This has dramatic implications for how simple and performant we can make our parser. These explicit boundaries also protect damage in a single block from bleeding into other blocks or tarnishing the entire document. It also allows the system to identify unrecognized blocks before rendering them. -_N.B.:_ The defining aspects of blocks are their semantics and the isolation mechanism they provide: in other words, their identity. On the other hand, where their data is stored is a more liberal aspect. Blocks support more than just static local data (via JSON literals inside the HTML comment or within the block's HTML), and more mechanisms (_e.g._, global blocks or otherwise resorting to storage in complementary `WP_Post` objects) are expected. See [attributes](/docs/designers-developers/developers/block-api/block-attributes.md) for details. +_N.B.:_ The defining aspects of blocks are their semantics and the isolation mechanism they provide: in other words, their identity. On the other hand, where their data is stored is a more liberal aspect. Blocks support more than just static local data (via JSON literals inside the HTML comment or within the block's HTML), and more mechanisms (_e.g._, global blocks or otherwise resorting to storage in complementary `WP_Post` objects) are expected. See [attributes](/docs/reference-guides/block-api/block-attributes.md) for details. ### The Anatomy of a Serialized Block diff --git a/docs/architecture/fse-templates.md b/docs/explanations/architecture/full-site-editing-templates.md similarity index 96% rename from docs/architecture/fse-templates.md rename to docs/explanations/architecture/full-site-editing-templates.md index 293b7f1f7bd303..11e8728ba1aa3f 100644 --- a/docs/architecture/fse-templates.md +++ b/docs/explanations/architecture/full-site-editing-templates.md @@ -1,8 +1,10 @@ -### Template and template part flows +# Full Site Editing Templates + +## Template and template part flows > This is the documentation for the current implementation of the block-based templates and template parts themes. This is part of the Full Site Editing project. These features are still experimental in the plugin. “Experimental” means this is just an early implementation that is subject to potential drastic and breaking changes in iterations based on feedback from users, contributors, and theme authors. -This document will explain the internals of how templates and templates parts are rendered in the frontend and edited in the backend. For an introduction about block-based themes and Full site editing templates, refer to the [block-based themes documentation](/docs/designers-developers/developers/themes/block-based-themes.md). +This document will explain the internals of how templates and templates parts are rendered in the frontend and edited in the backend. For an introduction about block-based themes and Full site editing templates, refer to the [block-based themes documentation](/docs/how-to-guides/themes/block-based-themes.md). ## Storage diff --git a/docs/explanations/architecture/key-concepts.md b/docs/explanations/architecture/key-concepts.md new file mode 100644 index 00000000000000..1aca3b60ff1ee8 --- /dev/null +++ b/docs/explanations/architecture/key-concepts.md @@ -0,0 +1,62 @@ +# Key Concepts + +## Blocks + +Blocks are an abstract unit for structuring and interacting with content. When composed together they create the content for a webpage. Everything from a paragraph, to a video, to the site title is represented as a block. + +Blocks come in many different forms but also provide a consistent interface. They can be inserted, moved, reordered, copied, duplicated, transformed, deleted, dragged, and combined. Blocks can also be reused, allowing them to be shared across posts and post types and/or used multiple times in the same post. If it helps, you can think of blocks as a more graceful shortcode, with rich formatting tools for users to compose content. + +The settings and content of a block can be customized in three main places: the block canvas, the block toolbar, and the block inspector. + +### Composability + +Blocks are meant to be combined in different ways. Blocks are hierarchical in that a block can be nested within another block. Nested blocks and its container are also called _children_ and _parent_ respectively. For example, a _Columns_ block can be the parent block to multiple child blocks in each of its columns. The API that governs child block usage is named `InnerBlocks`. + +### Data & Attributes + +Blocks understand content as attributes and are serializable to HTML. To this point, there is a new Block Grammar. Distilled, the block grammar is an HTML comment, either a self-closing tag or with a beginning tag and ending tag. In the main tag, depending on the block type and user customizations, there can be a JSON object. This raw form of the block is referred to as serialized. + +```html + +

Welcome to the world of blocks.

+ +``` + +Blocks can be static or dynamic. Static blocks contain rendered content and an object of Attributes used to re-render based on changes. Dynamic blocks require server-side data and rendering while the post content is being generated (rendering). + +Each block contains Attributes or configuration settings, which can be sourced from raw HTML in the content via meta or other customizable origins. + +### Transformations + +Blocks have the ability to be transformed into other block types. This allows basic operations like converting a paragraph into a heading, but also more intricate ones like multiple images becoming a gallery. Transformations work for single blocks and for multi-block selections. Internal block variations are also possible transformation targets. + +### Variations + +Given a block type, a block variation is a predefined set of its initial attributes. This API allows creating a single block from which multiple configurations are possible. Variations provide different possible interfaces, including showing up as entirely new blocks in the library, or as presets when inserting a new block. Read [the API documentation](/docs/reference-guides/block-api/block-registration.md#variations-optional) for more details. + +**More on Blocks** + +- **[Block API](/docs/reference-guides/block-api/README.md)** +- **[Tutorial: Building A Custom Block](/docs/getting-started/tutorials/create-block/README.md)** + +## Reusable Blocks + +A reusable blocks is a block (or multiple blocks) that can be inserted and edited globally at once. If a reusable block is edited in one place, those changes are reflected across all posts and pages that that block is used. Examples of reusable blocks include a block consisting of a heading whose content and a custom color that would be appear on multiple pages of the site and sidebar widgets that would appear on every page. + +Any edits to a reusable block will appear on every other use of that block, saving time from having to make the same edit on different posts. + +In technical details, reusable blocks are stored as a hidden post type (`wp_block`) and are dynamic blocks that "ref" or reference the `post_id` and return the `post_content` for that block. + +## Patterns + +A [block pattern](/docs/reference-guides/block-api/block-patterns.md) is a group of blocks that have been combined together creating a design pattern. These design patterns provide a starting point for building more advanced pages and layouts quickly. A block pattern can be as small as a single block or as large as a full page of content. Unlike reusable blocks, once a pattern is inserted it doesn't remain in sync with the original content as the blocks contained are meant to be edited and customized by the user. Underneath the surface, patterns are just regular blocks composed together. Themes can register patterns to offer users quick starting points with a design language familiar to that theme's aesthetics. + +## Templates (in progress) + +While the post editor concentrates on the content of a post, the [template](/docs/reference-guides/block-api/block-templates.md) editor allows declaring and editing an entire site using blocks, from header to footer. To support these efforts there's a collection of blocks that interact with different parts of a site (like the site title, description, logo, navigation, etc) as well as semantic areas like header, sidebar, and footer. Templates are broken down between templates (that describe a full page) and template parts (that describe reusable areas within a template). These templates and template parts can be composed together and registered by a theme. They are also entirely editable by users using the block editor. Customized templates are saved in a `wp_template` post type. Block templates include both static pages and dynamic ones, like archives, singular, home, 404, etc. + +Note: custom post types can also be initialized with a starting `post_content` template that should not be confused with the theme template system described above. + +## Global Styles (in progress) + +Describes a set of configuration and default properties of blocks and their visual aspects. Global Styles is both an interface (which users access through the site editor) and a configuration system done through [a `theme.json` file](/docs/how-to-guides/themes/theme-json.md). This file absorbs most of the configuration aspects usually scattered through various `add_theme_support` calls to simplify communicating with the editor. It thus aims to improve declaring what settings should be enabled, what attributes are supported, what specific tools a theme offers (like a custom color palette), the available design tools present both globally and on each block, and an infrastructure that allows to enqueue only the relevant CSS based on what blocks are used on a page. diff --git a/docs/architecture/modularity.md b/docs/explanations/architecture/modularity.md similarity index 98% rename from docs/architecture/modularity.md rename to docs/explanations/architecture/modularity.md index 7f73a12ebadd61..0f80bc01a50b65 100644 --- a/docs/architecture/modularity.md +++ b/docs/explanations/architecture/modularity.md @@ -72,7 +72,7 @@ In the context of existing WordPress pages, if you omit to define the scripts or #### Packages with data stores -Some WordPress production packages define data stores to handle their state. These stores can also be used by third-party plugins and themes to retrieve data and to manipulate it. The name of these data stores is also normalized following this format `core/package-name` (E.g. the `@wordpress/block-editor` package defines and uses the `core/block-editor` package). +Some WordPress production packages define data stores to handle their state. These stores can also be used by third-party plugins and themes to retrieve data and to manipulate it. The name of these data stores is also normalized following this format `core/package-name` (E.g. the `@wordpress/block-editor` package defines and uses the `core/block-editor` data store). If you're using one of these stores to access and manipulate WordPress data in your plugins, don't forget to add the corresponding WordPress script to your own script dependencies for your plugin to work properly. (For instance, if you're retrieving data from the `core/block-editor` store, you should add the `wp-block-editor` package to your script dependencies like shown above). @@ -100,4 +100,4 @@ Structured this way, these packages can be used in a variety of combinations out ## Going further - - [Package Reference](/docs/designers-developers/developers/packages.md) + - [Package Reference](/docs/reference-guides/packages.md) diff --git a/docs/architecture/performance.md b/docs/explanations/architecture/performance.md similarity index 96% rename from docs/architecture/performance.md rename to docs/explanations/architecture/performance.md index e4473b2350f1f2..a886beaf73850b 100644 --- a/docs/architecture/performance.md +++ b/docs/explanations/architecture/performance.md @@ -4,7 +4,7 @@ Performance is a key feature for editor applications and the Block editor is not ## Metrics -To ensure the block editor stays performant across releases and development, we monitor some key metrics using [performance testing](/docs/contributors/testing-overview.md#performance-testing). +To ensure the block editor stays performant across releases and development, we monitor some key metrics using [performance testing](/docs/contributors/code/testing-overview.md#performance-testing). **Loading Time:** The time it takes to load an editor page. **Typing Time:** The time it takes for the browser to respond while typing on the editor. diff --git a/docs/getting-started/README.md b/docs/getting-started/README.md new file mode 100644 index 00000000000000..82eb07d95d9858 --- /dev/null +++ b/docs/getting-started/README.md @@ -0,0 +1,14 @@ +# Getting Started + +## [Tutorials](/docs/getting-started/tutorials/README.md) + +- [Development Environment](/docs/getting-started/tutorials/devenv/README.md) +- [Create a Block Tutorial](/docs/getting-started/tutorials/create-block/README.md) + +## [Glossary](/docs/getting-started/glossary.md) + +## [FAQ](/docs/getting-started/faq.md) + +## [History](/docs/getting-started/history.md) + +## [Outreach](/docs/getting-started/outreach.md) diff --git a/docs/designers-developers/faq.md b/docs/getting-started/faq.md similarity index 94% rename from docs/designers-developers/faq.md rename to docs/getting-started/faq.md index f0459b8e79f3e0..aba712e9b0b17d 100644 --- a/docs/designers-developers/faq.md +++ b/docs/getting-started/faq.md @@ -320,7 +320,13 @@ Blocks are able to provide base structural CSS styles, and themes can add styles Other features, like the new _wide_ and _full-wide_ alignment options, are simply CSS classes applied to blocks that offer this alignment. We are looking at how a theme can opt in to this feature, for example using `add_theme_support`. -This is currently a work in progress and we recommend reviewing the [block based theme documentation](https://developer.wordpress.org/block-editor/tutorials/block-based-themes/) to learn more. +This is currently a work in progress and we recommend reviewing the [block based theme documentation](/docs/how-to-guides/block-based-theme/README.md) to learn more. + +## What are block variations? Are they the same as block styles? + +No, [block variations](/docs/reference-guides/block-api/block-variations.md) are different versions of a single base block, sharing a similar functionality, but with slight differences in their implementation, or settings (attributes, InnerBlocks,etc). Block variations are transparent for users, and once there is a registered block variation, it will appear as a new block. For example, the `embed` block registers different block variations to embed content from specific providers. + +Meanwhile, [block styles](/docs/reference-guides/filters/block-filters.md#block-style-variations) allow you to provide alternative styles to existing blocks, and they work by adding a className to the block’s wrapper. Once a block has registered block styles, a block style selector will appear in its sidebar so that users can choose among the different registered styles. ## How do editor styles work? @@ -333,7 +339,7 @@ function gutenbergtheme_editor_styles() { add_action( 'enqueue_block_editor_assets', 'gutenbergtheme_editor_styles' ); ``` -*See:* [Editor Styles](/docs/designers-developers/developers/themes/theme-support.md#editor-styles) +*See:* [Editor Styles](/docs/how-to-guides/themes/theme-support.md#editor-styles) ## Should I be concerned that Gutenberg will make my plugin obsolete? @@ -384,7 +390,7 @@ Our approach—as outlined in [the technical overview introduction](https://make This also [gives us the flexibility](https://github.com/WordPress/gutenberg/issues/1516) to store those blocks that are inherently separate from the content stream (reusable pieces like widgets or small post type elements) elsewhere, and just keep token references for their placement. -We suggest you look at the [Gutenberg key concepts](/docs/designers-developers/key-concepts.md) to learn more about how this aspect of the project works. +We suggest you look at the [Gutenberg key concepts](/docs/getting-started/architecture/key-concepts.md) to learn more about how this aspect of the project works. ## How can I parse the post content back out into blocks in PHP or JS? In JS: diff --git a/docs/designers-developers/glossary.md b/docs/getting-started/glossary.md similarity index 100% rename from docs/designers-developers/glossary.md rename to docs/getting-started/glossary.md diff --git a/docs/contributors/history.md b/docs/getting-started/history.md similarity index 100% rename from docs/contributors/history.md rename to docs/getting-started/history.md diff --git a/docs/getting-started/outreach.md b/docs/getting-started/outreach.md new file mode 100644 index 00000000000000..7c289f6b07c38e --- /dev/null +++ b/docs/getting-started/outreach.md @@ -0,0 +1,80 @@ +# Outreach + +This includes articles, talks, demos and anything the community is doing to discuss, learn about, and contribute to Gutenberg. This is not an exhaustive list; if we are missing your event or article, just let us know in the [#core-editor slack channel](https://make.wordpress.org/chat/). + +## Articles + +A short list of useful articles around defining, extending, and contributing to Gutenberg. + +### Overviews of Gutenberg +- [Status Check: Site Editing & Customization](https://make.wordpress.org/core/2020/12/10/status-check-site-editing-and-customization/), Matías Ventura Bausero (December 2020) +- [Embrace the Modularity](https://riad.blog/2020/01/28/embrace-the-modularity/), Riad Benguella (January 2020) +- [The Language of Gutenberg](https://lamda.blog/2018/04/22/the-language-of-gutenberg/), Miguel Fonseca (April 2018) +- [Gutenberg, or the Ship of Theseus](https://matiasventura.com/post/gutenberg-or-the-ship-of-theseus/), Matías Ventura Bausero (October 2017) +- [We Called It Gutenberg for a Reason](https://ma.tt/2017/08/we-called-it-gutenberg-for-a-reason/), Matt Mullenweg (August 2017) +- [How Gutenberg is Changing WordPress Development](https://riad.blog/2017/10/06/how-gutenberg-is-changing-wordpress-development/), Riad Benguella (October 2017) +- [How Gutenberg Will Shape the Future of WordPress](https://www.linkedin.com/pulse/gutenberg-morten-rand-hendriksen/), Morten Rand-Henrikson (August 2017) + +You can view this [Index of Gutenberg related posts](https://make.wordpress.org/core/handbook/references/keeping-up-with-gutenberg-index/) for more information. + +### Extending Gutenberg +- [How to Start Block Development with Scaffolding](https://gziolo.pl/2020/12/22/how-to-start-block-development-with-scaffolding/), Grzegorz Ziółkowski (December 2020) +- [Introducing BlockBook for WordPress](https://riad.blog/2020/07/22/introducing-blockbook-for-wordpress/), Riad Benguella (July 2020) +- [AsBlocks: an encrypted collaborative environment](https://riad.blog/2020/06/11/write-as-blocks-in-an-encrypted-collaborative-environment/), Riad Benguella (June 2020) +- [Thoughts on Themes](https://matiasventura.com/post/thoughts-on-themes/), Matías Ventura Bausero (April 2020) +- [Build a Block Series](https://mkaz.blog/code/build-a-block-series-1/), Marcus Kazmierczak (January 2020) +- [With Gutenberg, what happens to my Custom Fields?](https://riad.blog/2017/12/11/with-gutenberg-what-happens-to-my-custom-fields/), Riad Benguella (December 2017) +- [One thousand and one ways to extend Gutenberg today](https://riad.blog/2017/10/16/one-thousand-and-one-way-to-extend-gutenberg-today/), Riad Benguella (October 2017) +- [Gutenberg Plugin Boilerplate](https://github.com/ahmadawais/Gutenberg-Boilerplate/), Ahmad Awais (August 2017) + +### Community Contribution +- [The WordPress block editor: a maintainer’s story](https://riad.blog/2020/10/26/the-wordpress-block-editor-a-maintainers-story/), Riad Benguella (October 2020) +- [Good first issue on Gutenberg](https://mkaz.blog/code/good-first-issue-on-gutenberg/), Marcus Kazmierczak (August 2020) +- [How to Use the New WordPress Block Editor](https://www.codeinwp.com/blog/wordpress-gutenberg-guide/), Colin Newcomer (July 2020) +- [WordPress Gutenberg Developer’s Guide](https://awhitepixel.com/guides/wordpress-gutenberg-developers-guide/), A White Pixel (2020) +- [Gutenberg Block Library](https://editorblockswp.com/library), Danny Cooper (August 2018) +- [A zero-configuration developer toolkit for building WordPress Gutenberg block plugins](https://ahmadawais.com/create-guten-block-toolkit/), Ahmad Awais (January 2018) +- [Contributing to Gutenberg Without Code](https://wordimpress.com/a-pot-stirrer-amongst-chefs-contributing-to-gutenberg-without-code/), Kevin Hoffman (August 2017) +- [Testing Flow in Gutenberg: Instructions for how to contribute to usability testing](https://make.wordpress.org/test/2017/11/22/testing-flow-in-gutenberg/), Anna Harrison (November 2017) + +### Article Compilations +- [Full-Site-Editing: MVP and Ultimate Resource List](https://gutenbergtimes.com/full-site-editing/), Birgit Pauli-Haack (February 2021) +- [Theme Shaper posts about Block Themes](https://themeshaper.com/tag/block-based-themes/), various authors (2020-2021) +- [Gutenberg Times Updates](https://gutenbergtimes.com/category/updates/), Birgit Pauli-Haack +- [Curated Collection of Gutenberg Articles, Plugins, Blocks, Tutorials, etc](http://gutenberghub.com/), Munir Kamal +- [Gutenberg articles on ManageWP.org](https://managewp.org/search?q=gutenberg) + + +## Talks + +Talks given about Gutenberg, including slides and videos as they are available. + +### Slides +- [Growing JavaScript Skills with WordPress](https://gziolo.pl/2019/07/15/growing-javascript-skills-with-wordpress/) at JavaScript for WordPress conference (July 2019) +- [The new core WordPress editor](http://kimb.me/talk-bigwp-london-new-core-wordpress-editor/) at BigWP London (May 2017) +- [Gutenberg Notes](http://haiku2.com/2017/09/bend-wordpress-meetup-gutenberg-notes/) at Bend WordPress Meetup (September 2017) +- [Gutenberg and the Future of Content in WordPress](https://www.slideshare.net/andrewmduthie/gutenberg-and-the-future-of-content-in-wordpress) (September 2017) +- [Head first into Gutenberg](https://speakerdeck.com/prtksxna/head-first-into-gutenberg) at the [WordPress Goa Meet-up](https://www.meetup.com/WordPressGoa/events/245275573/) (December 2017) +- [Gutenberg : vers une approche plus fine du contenu](https://imathi.eu/2018/02/16/gutenberg-vers-une-approche-plus-fine-du-contenu/) at [WP Paris](https://wpparis.fr/) (February 2018) + +### Videos +- [All `Gutenberg` tagged Talks at WordPress.tv](https://wordpress.tv/tag/gutenberg/) +- [Themes of the Future](https://wordpress.tv/2021/01/21/eileen-violini-themes-of-the-future-the-new-frontier-of-gutenberg-block-based-themes-and-theme-development/), Eileen Violini (January 2021) +- [Content Creation in WordPress using Gutenberg](https://wordpress.tv/2021/02/06/sayed-taqui-content-creation-in-wordpress-using-gutenberg/), +Sayed Taqui (January 2021) +- [Updates on WordPress Site-Editor (FSE) and Themes](https://www.youtube.com/watch?v=z-5OJq-OBjI&t), Gutenberg Times (January 2021) +- [State of the Word 2020 FSE Demo](https://youtu.be/QI3qCoiuG3w?t=1279), Matt Mullenweg (December 2020) +- [Full Site Editing! It's Coming, But Will Change How We Use WordPress?](https://www.youtube.com/watch?v=JHxsDSAImn0), WPCrafter.com (December 2020) +- [Advanced Layouts with the Block Editor](https://wordpress.tv/2020/12/06/advanced-layouts-with-the-block-editor/), Mel Choyce (December 2020) +- [State of the Word 2019 Gutenberg Demo](https://www.youtube.com/watch?v=LezbkeV059Q), Matt Mullenweg (December 2019) +- [Beyond Gutenberg](https://wordpress.tv/2018/07/09/matias-ventura-beyond-gutenberg/), Matías Ventura Bausero (July 2018) +- [Anatomy of a block: Gutenberg design patterns](https://wordpress.tv/2018/07/08/tammie-lister-anatomy-of-a-block-gutenberg-design-patterns/), Tammie Lister (July 2018) +- [State of the Word 2017 Gutenberg Demo](https://youtu.be/XOY3ZUO6P0k?t=2100), Matt Mullenweg with demo by Matías Ventura Bausero (December 2017) +- [Gutenberg is Coming (Don’t Be Afraid)](https://training.ithemes.com/webinar/gutenberg-is-coming-dont-be-afraid/), iThemes Training (September 2017) + +## Learn WordPress Courses + +You can access all courses [here](https://learn.wordpress.org/). +- [Registering Block Patterns](https://learn.wordpress.org/workshop/registering-block-patterns/), Daisy Olsen (January 2021) +- [Intro to Gutenberg Block Development](https://learn.wordpress.org/workshop/intro-to-gutenberg-block-development/), Jonathan Bossenger (August 2020) +- [Intro to Publishing with the Block Editor](https://learn.wordpress.org/workshop/intro-to-publishing-with-the-block-editor/), Erica Varlese (August 2020) diff --git a/docs/getting-started/tutorials/README.md b/docs/getting-started/tutorials/README.md new file mode 100644 index 00000000000000..7dea27c0fd2355 --- /dev/null +++ b/docs/getting-started/tutorials/README.md @@ -0,0 +1,19 @@ +# Tutorials + +- First things first, see [setting up your development environment](/docs/getting-started/tutorials/devenv/README.md) for the tools and setup you need to extend the block editor. + +- See the [Getting Started with JavaScript Tutorial](/docs/how-to-guides/javascript/README.md) to learn about how to use JavaScript within WordPress. + +- Beginners: The [Create a Block Tutorial](/docs/getting-started/tutorials/create-block/README.md) walks through creating a block plugin using the `@wordpress/create-block` package; a quick and easy way to start creating your own block. + +- Intermediate: The [Block Tutorial](/docs/how-to-guides/block-tutorial/README.md) covers different aspects of block development. The documentation is slightly dated but still valid, if you are new to block development, start with the Create Block Tutorial above. + +- See the [Meta Boxes Tutorial](/docs/how-to-guides/metabox/README.md) for new ways of extending the editor storing and using post meta data. + +- Check out the [Notices Tutorial](/docs/how-to-guides/notices/README.md) to learn how to display informational UI at the top of the editor. + +- The [Sidebar Tutorial](/docs/how-to-guides/sidebar-tutorial/plugin-sidebar-0.md) will walk you through the steps of creating a sidebar to update data from the `post_meta` table. + +- Learn how to add customized buttons to the toolbar with the [Format API tutorial](/docs/how-to-guides/format-api/). + +- Build your own [custom block editor instance](/docs/reference-guides/platform/custom-block-editor/) - this will walk you through building a standalone instance of the block editor within WP Admin. diff --git a/docs/designers-developers/developers/tutorials/create-block/readme.md b/docs/getting-started/tutorials/create-block/README.md similarity index 68% rename from docs/designers-developers/developers/tutorials/create-block/readme.md rename to docs/getting-started/tutorials/create-block/README.md index 5e050ade6c8428..75719ca9a85e6a 100644 --- a/docs/designers-developers/developers/tutorials/create-block/readme.md +++ b/docs/getting-started/tutorials/create-block/README.md @@ -6,7 +6,7 @@ The tutorial includes setting up your development environment, tools, and gettin ## Prerequisites -The first thing you need is a development environment and tools. This includes setting up your WordPress environment, Node, NPM, and your code editor. If you need help, see the [setting up your development environment documentation](/docs/designers-developers/developers/tutorials/devenv/readme.md). +The first thing you need is a development environment and tools. This includes setting up your WordPress environment, Node, NPM, and your code editor. If you need help, see the [setting up your development environment documentation](/docs/getting-started/tutorials/devenv/README.md). ## Quick Start @@ -28,9 +28,10 @@ After activated, go to the block editor and use the inserter to search and add y The create a block tutorials breaks down to the following sections. -1. [WordPress Plugin](/docs/designers-developers/developers/tutorials/create-block/wp-plugin.md) -2. [Anatomy of a Gutenberg Block ](/docs/designers-developers/developers/tutorials/create-block/block-anatomy.md) -3. [Block Attributes](/docs/designers-developers/developers/tutorials/create-block/attributes.md) -4. [Code Implementation](/docs/designers-developers/developers/tutorials/create-block/block-code.md) -5. [Authoring Experience](/docs/designers-developers/developers/tutorials/create-block/author-experience.md) -6. [Finishing Touches](/docs/designers-developers/developers/tutorials/create-block/finishing.md) +1. [WordPress Plugin](/docs/getting-started/tutorials/create-block/wp-plugin.md) +2. [Anatomy of a Gutenberg Block ](/docs/getting-started/tutorials/create-block/block-anatomy.md) +3. [Block Attributes](/docs/getting-started/tutorials/create-block/attributes.md) +4. [Code Implementation](/docs/getting-started/tutorials/create-block/block-code.md) +5. [Authoring Experience](/docs/getting-started/tutorials/create-block/author-experience.md) +6. [Finishing Touches](/docs/getting-started/tutorials/create-block/finishing.md) +7. [Share your Block with the World](/docs/getting-started/tutorials/create-block/submitting-to-block-directory.md) diff --git a/docs/designers-developers/developers/tutorials/create-block/attributes.md b/docs/getting-started/tutorials/create-block/attributes.md similarity index 90% rename from docs/designers-developers/developers/tutorials/create-block/attributes.md rename to docs/getting-started/tutorials/create-block/attributes.md index 5614987e33fa03..2c3360db158af4 100644 --- a/docs/designers-developers/developers/tutorials/create-block/attributes.md +++ b/docs/getting-started/tutorials/create-block/attributes.md @@ -18,11 +18,11 @@ Add this to the `index.js` file within the `registerBlockType` function. The `at When the block loads it will look at the saved content for the block, look for the div tag, take the text portion, and store the content in an `attributes.message` variable. -Note: The text portion is equivalent to `innerText` attribute of a DOM element. For more details and other examples see the [Block Attributes documentation](/docs/designers-developers/developers/block-api/block-attributes.md). +Note: The text portion is equivalent to `innerText` attribute of a DOM element. For more details and other examples see the [Block Attributes documentation](/docs/reference-guides/block-api/block-attributes.md). ## Edit and Save -The **attributes** are passed to the `edit` and `save` functions, along with a **setAttributes** function to set the values. Additional parameters are also passed in to this functions, see [the edit/save documentation](/docs/designers-developers/developers/block-api/block-edit-save.md) for more details. +The **attributes** are passed to the `edit` and `save` functions, along with a **setAttributes** function to set the values. Additional parameters are also passed in to this functions, see [the edit/save documentation](/docs/reference-guides/block-api/block-edit-save.md) for more details. The `attributes` is a JavaScript object containing the values of each attribute, or default values if defined. The `setAttributes` is a function to update an attribute. @@ -71,4 +71,4 @@ export default function Save( { attributes, className } ) { Rebuild the block using `npm run build`, reload the editor and add the block. Type a message in the editor, save, and view it in the post. -Next Section: [Code Implementation](/docs/designers-developers/developers/tutorials/create-block/block-code.md) +Next Section: [Code Implementation](/docs/getting-started/tutorials/create-block/block-code.md) diff --git a/docs/designers-developers/developers/tutorials/create-block/author-experience.md b/docs/getting-started/tutorials/create-block/author-experience.md similarity index 97% rename from docs/designers-developers/developers/tutorials/create-block/author-experience.md rename to docs/getting-started/tutorials/create-block/author-experience.md index accd856ae2562f..a79b73e5d07b9f 100644 --- a/docs/designers-developers/developers/tutorials/create-block/author-experience.md +++ b/docs/getting-started/tutorials/create-block/author-experience.md @@ -139,4 +139,4 @@ export default function Edit( { attributes, className, setAttributes } ) { } ``` -Next Section: [Finishing Touches](/docs/designers-developers/developers/tutorials/create-block/finishing.md) +Next Section: [Finishing Touches](/docs/getting-started/tutorials/create-block/finishing.md) diff --git a/docs/designers-developers/developers/tutorials/create-block/block-anatomy.md b/docs/getting-started/tutorials/create-block/block-anatomy.md similarity index 84% rename from docs/designers-developers/developers/tutorials/create-block/block-anatomy.md rename to docs/getting-started/tutorials/create-block/block-anatomy.md index 2eea119b98ecd2..0e99d24a3c2c7d 100644 --- a/docs/designers-developers/developers/tutorials/create-block/block-anatomy.md +++ b/docs/getting-started/tutorials/create-block/block-anatomy.md @@ -2,7 +2,7 @@ At its simplest, a block in the WordPress block editor is a JavaScript object with a specific set of properties. -**Note:** Block development uses ESNext syntax, this refers to the latest JavaScript standard. If this is unfamiliar, I recommend reviewing the [ESNext syntax documentation](/docs/designers-developers/developers/tutorials/javascript/esnext-js.md) to familiarize yourself with the newer syntax used in modern JavaScript development. +**Note:** Block development uses ESNext syntax, this refers to the latest JavaScript standard. If this is unfamiliar, I recommend reviewing the [ESNext syntax documentation](/docs/how-to-guides/javascript/esnext-js.md) to familiarize yourself with the newer syntax used in modern JavaScript development. Here is the complete code for registering a block: @@ -35,13 +35,13 @@ registerBlockType( 'create-block/gutenpride', { The first parameter in the **registerBlockType** function is the block name, this should match exactly to the name registered in the PHP file. -The second parameter to the function is the block object. See the [block registration documentation](/docs/designers-developers/developers/block-api/block-registration.md) for full details. +The second parameter to the function is the block object. See the [block registration documentation](/docs/reference-guides/block-api/block-registration.md) for full details. The **title** is the title of the block shown in the Inserter. The **icon** is the icon shown in the Inserter. The icon property expects any Dashicon name as a string, see [list of available icons](https://developer.wordpress.org/resource/dashicons/). You can also provide an SVG object, but for now it's easiest to just pick a Dashicon name. -The **category** specified is a string and must be one of: "common, formatting, layout, widgets, or embed". You can create your own custom category name, [see documentation for details](/docs/designers-developers/developers/filters/block-filters.md#managing-block-categories). For this tutorial, I specified "widgets" as the category. +The **category** specified is a string and must be one of: "common, formatting, layout, widgets, or embed". You can create your own custom category name, [see documentation for details](/docs/reference-guides/filters/block-filters.md#managing-block-categories). For this tutorial, I specified "widgets" as the category. The last two block object properties are **edit** and **save**, these are the key parts of a block. Both properties should be defined as functions. @@ -61,4 +61,4 @@ __( 'Gutenpride', 'gutenpride' ); This is an internationalization wrapper that allows for the string "Gutenpride" to be translated. The second parameter, "gutenpride" is called the text domain and gives context for where the string is from. The JavaScript internationalization, often abbreviated i18n, matches the core WordPress internationalization process. See the [Internationalization in Plugin Developer Handbook](https://developer.wordpress.org/plugins/internationalization/) for more details. -Next Section: [Block Attributes](/docs/designers-developers/developers/tutorials/create-block/attributes.md) +Next Section: [Block Attributes](/docs/getting-started/tutorials/create-block/attributes.md) diff --git a/docs/designers-developers/developers/tutorials/create-block/block-code.md b/docs/getting-started/tutorials/create-block/block-code.md similarity index 96% rename from docs/designers-developers/developers/tutorials/create-block/block-code.md rename to docs/getting-started/tutorials/create-block/block-code.md index 61a4b920aab95f..23541de7ecb59c 100644 --- a/docs/designers-developers/developers/tutorials/create-block/block-code.md +++ b/docs/getting-started/tutorials/create-block/block-code.md @@ -65,4 +65,4 @@ Update **gutenpride.php** to enqueue from generated file location: $editor_css = "build/index.css"; ``` -Next Section: [Authoring Experience](/docs/designers-developers/developers/tutorials/create-block/author-experience.md) +Next Section: [Authoring Experience](/docs/getting-started/tutorials/create-block/author-experience.md) diff --git a/docs/designers-developers/developers/tutorials/create-block/finishing.md b/docs/getting-started/tutorials/create-block/finishing.md similarity index 65% rename from docs/designers-developers/developers/tutorials/create-block/finishing.md rename to docs/getting-started/tutorials/create-block/finishing.md index 902256137898c2..1691547970414d 100644 --- a/docs/designers-developers/developers/tutorials/create-block/finishing.md +++ b/docs/getting-started/tutorials/create-block/finishing.md @@ -10,16 +10,16 @@ You can visually browse the components and what their implementation looks like ## Additional Tutorials -The **RichText component** allows for creating a richer input besides plain text, allowing for bold, italic, links, and other inline formating. See the [RichText Reference](/docs/designers-developers/developers/richtext.md) for documentation using this component. +The **RichText component** allows for creating a richer input besides plain text, allowing for bold, italic, links, and other inline formating. See the [RichText Reference](/docs/reference-guides/richtext.md) for documentation using this component. -The InspectorPanel (the settings on the right for a block) and Block Controls (toolbar controls) have a standard way to be implemented. See the [Block controls tutorial](/docs/designers-developers/developers/tutorials/block-tutorial/block-controls-toolbar-and-sidebar.md) for additional information. +The InspectorPanel (the settings on the right for a block) and Block Controls (toolbar controls) have a standard way to be implemented. See the [Block controls tutorial](/docs/how-to-guides/block-tutorial/block-controls-toolbar-and-sidebar.md) for additional information. -The [Sidebar tutorial](/docs/designers-developers/developers/tutorials/sidebar-tutorial/plugin-sidebar-0.md) is a good resource on how to create a sidebar for your plugin. +The [Sidebar tutorial](/docs/how-to-guides/sidebar-tutorial/plugin-sidebar-0.md) is a good resource on how to create a sidebar for your plugin. -Nested blocks, a block that contains additional blocks, is a common pattern used by various blocks such as Columns, Cover, and Social Links. The **InnerBlocks component** enables this functionality, see the [Using InnerBlocks documentation](/docs/designers-developers/developers/tutorials/block-tutorial/nested-blocks-inner-blocks.md). +Nested blocks, a block that contains additional blocks, is a common pattern used by various blocks such as Columns, Cover, and Social Links. The **InnerBlocks component** enables this functionality, see the [Using InnerBlocks documentation](/docs/how-to-guides/block-tutorial/nested-blocks-inner-blocks.md). ## How did they do that One of the best sources for information and reference is the Block Editor itself, all the core blocks are built the same way. A good way to learn how things are done is to find a core block code that does something close to what you are interested in and then using the same approach for your own block. -All core blocks source are in the [block library package on Github](https://github.com/WordPress/gutenberg/tree/master/packages/block-library/src). +All core blocks source are in the [block library package on Github](https://github.com/WordPress/gutenberg/tree/HEAD/packages/block-library/src). diff --git a/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md b/docs/getting-started/tutorials/create-block/submitting-to-block-directory.md similarity index 65% rename from docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md rename to docs/getting-started/tutorials/create-block/submitting-to-block-directory.md index b84ff46b041fd9..220c30a174ea49 100644 --- a/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md +++ b/docs/getting-started/tutorials/create-block/submitting-to-block-directory.md @@ -3,6 +3,7 @@ So you've created an awesome block? Care to share? **Contents**: + 1. Help users understand your block 2. Analyze your plugin 3. Zip & Submit @@ -13,10 +14,10 @@ It is important to the Block Directory and our end users to provide easy to unde **Guidelines**: -- Name your block based on what it does -- Clearly describe your block -- Add Keywords for all contexts -- Choose the right category +- Name your block based on what it does +- Clearly describe your block +- Add Keywords for all contexts +- Choose the right category ### Name your block based on what it does @@ -33,47 +34,50 @@ Try your best to make your block's name functional and unique to make it stand o The description really helps to communicate what your block does.The quicker a user understands how your block will help them, the more likely it is a user will use your block. Users will be reading your block's description within the Block Editor where space can be limited. Try to keep it short and concise. **Not So Good**: The best way to show images on your website using jQuery and CSS. -**Good**: A responsive image gallery block. +**Good**: A responsive image gallery block. **Tip**: It’s not about marketing your block, in fact we want to avoid marketing in blocks. You can read more about it in the [plugin guidelines]. Stick to being as clear as you can. The Block Directory will provide metrics to let users know how awesome your block is! ### Add Keywords for broader context -Keywords add extra context to your block and make it more likely to be found in the inserter. +Keywords add extra context to your block and make it more likely to be found in the inserter. Examples for an Image Slider block: -- slider -- carousel -- gallery -[Read more about keywords.](https://github.com/WordPress/gutenberg/blob/master/docs/designers-developers/developers/block-api/block-metadata.md#keywords) +- slider +- carousel +- gallery + +[Read more about keywords.](/docs/reference-guides/block-api/block-metadata.md#keywords) ### Choose the right category The Block Editor allows you to indicate the category your block belongs in, making it easier for users to locate your block in the menu. **Possible Values**: -- text -- media -- design -- widgets -- embed -[Read more about categories.](https://github.com/WordPress/gutenberg/blob/master/docs/designers-developers/developers/block-api/block-metadata.md#category) +- text +- media +- design +- widgets +- embed + +[Read more about categories.](/docs/reference-guides/block-api/block-metadata.md#category) Wondering where to input all this information? Read the next section :) ## Step 2: Analyze your plugin -Each block in your plugin should have a corresponding `block.json` file. This file provides the Block Directory important information about your block. Along with being the place to store contextual information about your block like the: `name`, `description`, `keywords` and `category`, the `block.json` file stores the location of your block’s files. + +Each block in your plugin should have a corresponding `block.json` file with the [block metadata](/docs/reference-guides/block-api/block-metadata.md). This file provides the Block Directory important information about your block. Along with being the place to store contextual information about your block like the: `name`, `description`, `keywords` and `category`, the `block.json` file stores the location of your block’s files. Block plugins submitted to the Block Directory can contain mutliple blocks only if they are children of a single parent/ancestor. There should only be one main block. For example, a list block can contain list-item blocks. Children blocks must set the `parent` property in their `block.json` file. Double check that the following is true for your block: -- `editorScript` is pointing to the JavaScript bundle that includes all the code used in the **editor**. -- `editorStyle` is pointing to the CSS bundle that includes all the css used in the **editor**. -- `script` is pointing to the JavaScript bundle that includes all the code used on the **website**. -- `style` is pointing to the CSS bundle that includes all the code used on the **website**. +- `editorScript` is pointing to the JavaScript bundle that includes all the code used in the **editor**. +- `editorStyle` is pointing to the CSS bundle that includes all the css used in the **editor**. +- `script` is pointing to the JavaScript bundle that includes all the code used on the **website**. +- `style` is pointing to the CSS bundle that includes all the code used on the **website**. We encourage the separation of code by using both editorScript/editorStyle and script/style files listed in your block.json to keep the backend and frontend interfaces running smoothly. Even though only one file is required. @@ -81,21 +85,19 @@ Here is an example of a basic block.json file. ```json { - "name": "plugin-slug/image-slider", - "title": "Responsive Image Slider", - "description": "A responsive and easy to use image gallery block.", - "keywords": [ "slider", "carousel", "gallery" ], - "category": "media", - "editorScript": "file:./dist/editor.js", + "name": "plugin-slug/image-slider", + "title": "Responsive Image Slider", + "description": "A responsive and easy to use image gallery block.", + "keywords": [ "slider", "carousel", "gallery" ], + "category": "media", + "editorScript": "file:./dist/editor.js" } ``` -The `block.json` file also contains other important properties. Take a look at an [example block.json](https://github.com/WordPress/gutenberg/blob/master/docs/designers-developers/developers/block-api/block-metadata.md) for additional properties to be included in the block.json file. - +The `block.json` file also contains other important properties. Take a look at an [example block.json](/docs/reference-guides/block-api/block-metadata.md) for additional properties to be included in the block.json file. ## Step 3: Zip & Submit The community is thankful for your contribution. It is time to submit your plugin. Go through [the block guidelines](https://github.com/WordPress/wporg-plugin-guidelines/blob/block-guidelines/blocks.md). Create a zip file of your block and go to the [block plugin validator](https://wordpress.org/plugins/developers/block-plugin-validator/) and upload your plugin. - diff --git a/docs/designers-developers/developers/tutorials/create-block/wp-plugin.md b/docs/getting-started/tutorials/create-block/wp-plugin.md similarity index 73% rename from docs/designers-developers/developers/tutorials/create-block/wp-plugin.md rename to docs/getting-started/tutorials/create-block/wp-plugin.md index abfe91bc62ea2e..d7185538fdee97 100644 --- a/docs/designers-developers/developers/tutorials/create-block/wp-plugin.md +++ b/docs/getting-started/tutorials/create-block/wp-plugin.md @@ -49,7 +49,7 @@ Let's confirm the plugin is loaded and working. -or- -(3B) If you are using `wp-env`, see [Development Environment setup](/docs/designers-developers/developers/tutorials/devenv/readme.md), then you should now run from inside the `gutenpride` directory: +(3B) If you are using `wp-env`, see [Development Environment setup](/docs/getting-started/tutorials/devenv/README.md), then you should now run from inside the `gutenpride` directory: ```sh wp-env start @@ -92,57 +92,27 @@ To load the built script, so it is run within the editor, you need to tell WordP ```php function create_block_gutenpride_block_init() { - $dir = __DIR__; - - $script_asset_path = "$dir/build/index.asset.php"; - if ( ! file_exists( $script_asset_path ) ) { - throw new Error( - 'You need to run `npm start` or `npm run build` for the "create-block/gutenpride" block first.' - ); - } - $index_js = 'build/index.js'; - $script_asset = require( $script_asset_path ); - wp_register_script( - 'create-block-gutenpride-block-editor', - plugins_url( $index_js, __FILE__ ), - $script_asset['dependencies'], - $script_asset['version'] - ); - wp_set_script_translations( 'create-block-gutenpride-block-editor', 'gutenpride' ); - - $editor_css = 'editor.css'; - wp_register_style( - 'create-block-gutenpride-block-editor', - plugins_url( $editor_css, __FILE__ ), - array(), - filemtime( "$dir/$editor_css" ) - ); - - $style_css = 'style.css'; - wp_register_style( - 'create-block-gutenpride-block', - plugins_url( $style_css, __FILE__ ), - array(), - filemtime( "$dir/$style_css" ) - ); - - register_block_type( 'create-block/gutenpride', array( - 'apiVersion' => 2, - 'editor_script' => 'create-block-gutenpride-block-editor', - 'editor_style' => 'create-block-gutenpride-block-editor', - 'style' => 'create-block-gutenpride-block', - ) ); + register_block_type_from_metadata( __DIR__ ); } add_action( 'init', 'create_block_gutenpride_block_init' ); ``` -The build process creates a secondary asset file that contains the list of dependencies and a file version based on the timestamp, this is the `index.asset.php` file. +The `register_block_type_from_metadata` function registers the block we are going to create and specifies the `editor_script` file handle registered from the metadata provided in `block.json` file. So now when the editor loads it will load this script. -The `wp_register_script` function registers a name, called the handle, and relates that name to the script file. The dependencies are used to specify if the script requires including other libraries. The version is specified so the browser will reload if the file changed. +```json +{ + "apiVersion": 2, + "name": "create-block/gutenpride", + "title": "Gutenpride", + "editorScript": "file:./build/index.js" +} +``` + +For the `editorScript` provided in the block metadata, the build process creates a secondary asset file that contains the list of dependencies and a file version based on the timestamp, this is the `index.asset.php` file. -The `wp_set_script_translations` function tells WordPress to load translations for this script, if they exist. See more about [translations & internationalization.](/docs/designers-developers/developers/internationalization.md) +The `wp_register_script` function used internally registers a name, called the handle, and relates that name to the script file. The dependencies are used to specify if the script requires including other libraries. The version is specified so the browser will reload if the file changed. -The `register_block_type` function registers the block we are going to create and specifies the editor_script file handle registered. So now when the editor loads it will load this script. +The `wp_set_script_translations` function tells WordPress to load translations for this script, if they exist. See more about [translations & internationalization.](/docs/how-to-guides/internationalization.md) With the above in place, create a new post to load the editor and check your plugin is in the inserter. You can use `/` to search, or click the box with the [+] and search for "Gutenpride" to find the block. @@ -154,10 +124,10 @@ To open the developer tools in Firefox, use the menu selecting Web Developer : T Try running `npm run start` that will start the watch process for automatic rebuilds. If you then make an update to `src/index.js` file, you will see the build run, and if you reload the WordPress editor you'll see the change. -For more info, see the build section of the [Getting Started with JavaScript tutorial](/docs/designers-developers/developers/tutorials/javascript/js-build-setup.md) in the Block Editor Handbook. +For more info, see the build section of the [Getting Started with JavaScript tutorial](/docs/how-to-guides/javascript/js-build-setup.md) in the Block Editor Handbook. ## Summary Hopefully, at this point, you have your plugin created and activated. We have the package.json with the `@wordpress/scripts` dependency, that defines the build and start scripts. The basic block is in place and can be added to the editor. -Next Section: [Anatomy of a Block](/docs/designers-developers/developers/tutorials/create-block/block-anatomy.md) +Next Section: [Anatomy of a Block](/docs/getting-started/tutorials/create-block/block-anatomy.md) diff --git a/docs/designers-developers/developers/tutorials/devenv/readme.md b/docs/getting-started/tutorials/devenv/README.md similarity index 97% rename from docs/designers-developers/developers/tutorials/devenv/readme.md rename to docs/getting-started/tutorials/devenv/README.md index 762956cbec499e..fa510dfbd62df4 100644 --- a/docs/designers-developers/developers/tutorials/devenv/readme.md +++ b/docs/getting-started/tutorials/devenv/README.md @@ -1,6 +1,6 @@ # Development Environment -This guide is for setting up your local environment for JavaScript development for creating plugins and tools to extend WordPress and the block editor. If you are looking to contribute to Gutenberg project itself, see additional documentation in the [Getting Started guide](/docs/contributors/getting-started.md). +This guide is for setting up your local environment for JavaScript development for creating plugins and tools to extend WordPress and the block editor. If you are looking to contribute to Gutenberg project itself, see additional documentation in the [Getting Started guide](/docs/contributors/code/getting-started-with-code-contribution.md). A development environment is a catch-all term for what you need setup on your computer to work. The three main pieces needed for our development environment are: @@ -8,7 +8,7 @@ A development environment is a catch-all term for what you need setup on your co 2. WordPress Development Site 3. Code Editor -## Quickstart +## Quick Start Here is a summary of the guide. See each section for additional details and explanations. @@ -17,10 +17,11 @@ Here is a summary of the guide. See each section for additional details and expl Download and install [Node Version Manager](https://github.com/nvm-sh/nvm) (nvm) ``` -curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.3/install.sh | bash +curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.37.2/install.sh | bash ``` Quit and restart terminal +Install the long-term support (lts) version of node. ``` nvm install --lts ``` @@ -114,7 +115,7 @@ There are several ways to run WordPress locally on your own computer, or you cou The WordPress [wp-env package](https://www.npmjs.com/package/@wordpress/env) lets you set up a local WordPress environment for building and testing plugins and themes, without any additional configuration. -The `wp-env` tool uses Docker to create a virtual machine to that runs the WordPress site. There are instructions available for installing Docker on [Windows 10 Pro](https://docs.docker.com/docker-for-windows/install/), [all other versions of Windows](https://docs.docker.com/toolbox/toolbox_install_windows/), [macOS](https://docs.docker.com/docker-for-mac/install/), and [Linux](https://docs.docker.com/v17.12/install/linux/docker-ce/ubuntu/#install-using-the-convenience-script). If using Ubuntu, see our additional notes for [help installing Docker on Ubuntu](/docs/designers-developers/developers/tutorials/devenv/docker-ubuntu.md). +The `wp-env` tool uses Docker to create a virtual machine to that runs the WordPress site. There are instructions available for installing Docker on [Windows 10 Pro](https://docs.docker.com/docker-for-windows/install/), [all other versions of Windows](https://docs.docker.com/toolbox/toolbox_install_windows/), [macOS](https://docs.docker.com/docker-for-mac/install/), and [Linux](https://docs.docker.com/v17.12/install/linux/docker-ce/ubuntu/#install-using-the-convenience-script). If using Ubuntu, see our additional notes for [help installing Docker on Ubuntu](/docs/getting-started/tutorials/devenv/docker-ubuntu.md). After you have installed Docker, go ahead and install the `wp-env` tool. This command will install the tool globally, which means you can run it from any directory: diff --git a/docs/designers-developers/developers/tutorials/devenv/docker-ubuntu.md b/docs/getting-started/tutorials/devenv/docker-ubuntu.md similarity index 100% rename from docs/designers-developers/developers/tutorials/devenv/docker-ubuntu.md rename to docs/getting-started/tutorials/devenv/docker-ubuntu.md diff --git a/docs/designers-developers/developers/README.md b/docs/how-to-guides/README.md similarity index 59% rename from docs/designers-developers/developers/README.md rename to docs/how-to-guides/README.md index f79b1564f1787d..8cc028f7b2e59f 100644 --- a/docs/designers-developers/developers/README.md +++ b/docs/how-to-guides/README.md @@ -1,18 +1,18 @@ -# Developer Documentation +# How-to Guides The new editor is highly flexible, like most of WordPress. You can build custom blocks, modify the editor's appearance, add special plugins, and much more. ## Creating Blocks -The editor is about blocks, and the main extensibility API is the Block API. It allows you to create your own static blocks, [Dynamic Blocks](/docs/designers-developers/developers/tutorials/block-tutorial/creating-dynamic-blocks.md) ( rendered on the server ) and also blocks capable of saving data to Post Meta for more structured content. +The editor is about blocks, and the main extensibility API is the Block API. It allows you to create your own static blocks, [Dynamic Blocks](/docs/how-to-guides/block-tutorial/creating-dynamic-blocks.md) ( rendered on the server ) and also blocks capable of saving data to Post Meta for more structured content. -If you want to learn more about block creation, see the [Create a Block tutorial](/docs/designers-developers/developers/tutorials/create-block/readme.md) for the best place to start. +If you want to learn more about block creation, see the [Create a Block tutorial](/docs/getting-started/tutorials/create-block/README.md) for the best place to start. ## Extending Blocks It is also possible to modify the behavior of existing blocks or even remove them completely using filters. -Learn more in the [Block Filters](/docs/designers-developers/developers/filters/block-filters.md) section. +Learn more in the [Block Filters](/docs/reference-guides/filters/block-filters.md) section. ## Extending the Editor UI @@ -20,26 +20,26 @@ Extending the editor UI can be accomplished with the `registerPlugin` API, allow Refer to the [Plugins](/packages/plugins/README.md) and [Edit Post](/packages/edit-post/README.md) section for more information. -You can also filter certain aspects of the editor; this is documented on the [Editor Filters](/docs/designers-developers/developers/filters/editor-filters.md) page. +You can also filter certain aspects of the editor; this is documented on the [Editor Filters](/docs/reference-guides/filters/editor-filters.md) page. ## Meta Boxes -Porting PHP meta boxes to blocks or sidebar plugins is highly encouraged, learn how through these [meta data tutorials](/docs/designers-developers/developers/tutorials/metabox/readme.md). +Porting PHP meta boxes to blocks or sidebar plugins is highly encouraged, learn how through these [meta data tutorials](/docs/how-to-guides/metabox/README.md). -See how the new editor [supports existing Meta Boxes](/docs/designers-developers/developers/backward-compatibility/meta-box.md). +See how the new editor [supports existing Meta Boxes](/docs/reference-guides/backward-compatibility/meta-box.md). ## Theme Support By default, blocks provide their styles to enable basic support for blocks in themes without any change. Themes can add/override these styles, or rely on defaults. -There are some advanced block features which require opt-in support in the theme. See [theme support](/docs/designers-developers/developers/themes/theme-support.md). +There are some advanced block features which require opt-in support in the theme. See [theme support](/docs/how-to-guides/themes/theme-support.md). ## Autocomplete -Autocompleters within blocks may be extended and overridden. Learn more about the [autocomplete](/docs/designers-developers/developers/filters/autocomplete-filters.md) filters. +Autocompleters within blocks may be extended and overridden. Learn more about the [autocomplete](/docs/reference-guides/filters/autocomplete-filters.md) filters. ## Block Parsing and Serialization Posts in the editor move through a couple of different stages between being stored in `post_content` and appearing in the editor. Since the blocks themselves are data structures that live in memory it takes a parsing and serialization step to transform out from and into the stored format in the database. -Customizing the parser is an advanced topic that you can learn more about in the [Extending the Parser](/docs/designers-developers/developers/filters/parser-filters.md) section. +Customizing the parser is an advanced topic that you can learn more about in the [Extending the Parser](/docs/reference-guides/filters/parser-filters.md) section. diff --git a/docs/designers-developers/developers/accessibility.md b/docs/how-to-guides/accessibility.md similarity index 100% rename from docs/designers-developers/developers/accessibility.md rename to docs/how-to-guides/accessibility.md diff --git a/docs/designers-developers/developers/backward-compatibility/README.md b/docs/how-to-guides/backward-compatibility/README.md similarity index 96% rename from docs/designers-developers/developers/backward-compatibility/README.md rename to docs/how-to-guides/backward-compatibility/README.md index da58849dec3223..82ede6ca49e0bb 100644 --- a/docs/designers-developers/developers/backward-compatibility/README.md +++ b/docs/how-to-guides/backward-compatibility/README.md @@ -34,7 +34,7 @@ Production packages use the `wp` global variable to provide APIs to third-party * Existing usage of the block should not break or be marked as invalid when the editor is loaded. * The styling of the existing blocks should be guaranteed. -* Markup changes should be limited to the minimum possible, but if a block needs to change its saved markup, making previous versions invalid, a [**deprecated version**](/docs/designers-developers/developers/block-api/block-deprecation.md) of the block should be added. +* Markup changes should be limited to the minimum possible, but if a block needs to change its saved markup, making previous versions invalid, a [**deprecated version**](/docs/reference-guides/block-api/block-deprecation.md) of the block should be added. ## Class names and DOM updates diff --git a/docs/designers-developers/developers/backward-compatibility/deprecations.md b/docs/how-to-guides/backward-compatibility/deprecations.md similarity index 95% rename from docs/designers-developers/developers/backward-compatibility/deprecations.md rename to docs/how-to-guides/backward-compatibility/deprecations.md index 64fcab1c424a0a..df0b5af1d781ea 100644 --- a/docs/designers-developers/developers/backward-compatibility/deprecations.md +++ b/docs/how-to-guides/backward-compatibility/deprecations.md @@ -2,18 +2,30 @@ For features included in the Gutenberg plugin, the deprecation policy is intended to support backward compatibility for two minor plugin releases, when possible. Features and code included in a stable release of WordPress are not included in this deprecation timeline, and are instead subject to the [versioning policies of the WordPress project](https://make.wordpress.org/core/handbook/about/release-cycle/version-numbering/). The current deprecations are listed below and are grouped by _the version at which they will be removed completely_. If your plugin depends on these behaviors, you must update to the recommended alternative before the noted version. +## 10.3.0 + +- Passing a tuple of components with `as` prop to `ActionItem.Slot` component is no longer supported. Please pass a component with `as` prop instead. Example: + ```diff + + ``` + ## 9.7.0 - `leftSidebar` prop in `InterfaceSkeleton` component has been removed. Use `secondarySidebar` prop instead. ## 8.6.0 -- Block API integration with [Block Context](https://github.com/WordPress/gutenberg/blob/master/docs/designers-developers/developers/block-api/block-context.md) was updated. When registering a block use `usesContext` and `providesContext` pair in JavaScript files and `uses_context` and `provides_context` pair in PHP files instead of previous pair `context` and `providesContext`. +- Block API integration with [Block Context](/docs/reference-guides/block-api/block-context.md) was updated. When registering a block use `usesContext` and `providesContext` pair in JavaScript files and `uses_context` and `provides_context` pair in PHP files instead of previous pair `context` and `providesContext`. ## 8.3.0 -- The PHP function `gutenberg_get_post_from_context` has been removed. Use [Block Context](https://github.com/WordPress/gutenberg/blob/master/docs/designers-developers/developers/block-api/block-context.md) instead. -- The old Block Pattern APIs `register_pattern`/`unregister_pattern` have been removed. Use the [new functions](https://github.com/WordPress/gutenberg/blob/master/docs/designers-developers/developers/block-api/block-patterns.md#register_block_pattern) instead. +- The PHP function `gutenberg_get_post_from_context` has been removed. Use [Block Context](/docs/reference-guides/block-api/block-context.md) instead. +- The old Block Pattern APIs `register_pattern`/`unregister_pattern` have been removed. Use the [new functions](/docs/reference-guides/block-api/block-patterns.md#register_block_pattern) instead. ## 5.5.0 @@ -281,6 +293,6 @@ For features included in the Gutenberg plugin, the deprecation policy is intende - `wp.blocks.BlockDescription` component removed. Please use the `description` block property instead. - `wp.blocks.InspectorControls.*` components removed. Please use `wp.components.*` components instead. -- `wp.blocks.source.*` matchers removed. Please use the declarative attributes instead. See [block attributes](/docs/designers-developers/developers/block-api/block-attributes.md) for more info. +- `wp.blocks.source.*` matchers removed. Please use the declarative attributes instead. See [block attributes](/docs/reference-guides/block-api/block-attributes.md) for more info. - `wp.data.select( 'selector', ...args )` removed. Please use `wp.data.select( reducerKey' ).*` instead. - `wp.blocks.MediaUploadButton` component removed. Please use `wp.blocks.MediaUpload` component instead. diff --git a/docs/designers-developers/developers/backward-compatibility/meta-box.md b/docs/how-to-guides/backward-compatibility/meta-box.md similarity index 97% rename from docs/designers-developers/developers/backward-compatibility/meta-box.md rename to docs/how-to-guides/backward-compatibility/meta-box.md index dc8ce593eb8565..ebffb327ffe7fe 100644 --- a/docs/designers-developers/developers/backward-compatibility/meta-box.md +++ b/docs/how-to-guides/backward-compatibility/meta-box.md @@ -1,6 +1,6 @@ # Meta Boxes -This is a brief document detailing how meta box support works in the block editor. With the superior developer and user experience of blocks, especially once block templates are available, **porting PHP meta boxes to blocks is highly encouraged!** See the [Meta Block tutorial](/docs/designers-developers/developers/tutorials/metabox/meta-block-1-intro.md) for how to store post meta data using blocks. +This is a brief document detailing how meta box support works in the block editor. With the superior developer and user experience of blocks, especially once block templates are available, **porting PHP meta boxes to blocks is highly encouraged!** See the [Meta Block tutorial](/docs/how-to-guides/metabox/meta-block-1-intro.md) for how to store post meta data using blocks. ### Testing, Converting, and Maintaining Existing Meta Boxes diff --git a/docs/designers-developers/developers/tutorials/block-based-themes/README.md b/docs/how-to-guides/block-based-theme/README.md similarity index 90% rename from docs/designers-developers/developers/tutorials/block-based-themes/README.md rename to docs/how-to-guides/block-based-theme/README.md index a701cd46228814..6497fd437bf559 100644 --- a/docs/designers-developers/developers/tutorials/block-based-themes/README.md +++ b/docs/how-to-guides/block-based-theme/README.md @@ -12,11 +12,11 @@ This tutorial is up to date as of Gutenberg version 9.1. ## Table of Contents - 1. [What is needed to create a block-based theme?](/docs/designers-developers/developers/tutorials/block-based-themes/README.md#what-is-needed-to-create-a-block-based-theme) - 2. [Creating the theme](/docs/designers-developers/developers/tutorials/block-based-themes/README.md#creating-the-theme) - 3. [Creating the templates and template parts](/docs/designers-developers/developers/tutorials/block-based-themes/README.md#creating-the-templates-and-template-parts) - 4. [Experimental-theme.json - Global styles](/docs/designers-developers/developers/tutorials/block-based-themes/README.md#experimental-theme-json-global-styles) - 5. [Adding blocks](/docs/designers-developers/developers/tutorials/block-based-themes/block-based-themes-2-adding-blocks.md) + 1. [What is needed to create a block-based theme?](/docs/how-to-guides/block-based-themes/README.md#what-is-needed-to-create-a-block-based-theme) + 2. [Creating the theme](/docs/how-to-guides/block-based-themes/README.md#creating-the-theme) + 3. [Creating the templates and template parts](/docs/how-to-guides/block-based-themes/README.md#creating-the-templates-and-template-parts) + 4. [experimental-theme.json - Global styles](/docs/how-to-guides/block-based-themes/README.md#experimental-theme-json-global-styles) + 5. [Adding blocks](/docs/how-to-guides/block-based-themes/block-based-themes-2-adding-blocks.md) ## What is needed to create a block-based theme? @@ -32,7 +32,7 @@ Each template or template part contains the [block grammar](https://developer.wo A block based theme requires an `index.php` file, an index template file, a `style.css` file, and a `functions.php` file. -The theme may optionally include an [experimental-theme.json file](/docs/designers-developers/developers/themes/theme-json.md) to manage global styles. You decide what additional templates and template parts to include in your theme. +The theme may optionally include an [experimental-theme.json file](/docs/how-to-guides/themes/theme-json.md) to manage global styles. You decide what additional templates and template parts to include in your theme. Templates are placed inside the `block-templates` folder, and template parts are placed inside the `block-template-parts` folder: @@ -377,4 +377,4 @@ Below are the presets and styles combined: } ``` -## [Adding blocks](/docs/designers-developers/developers/tutorials/block-based-themes/block-based-themes-2-adding-blocks.md) +## [Adding blocks](/docs/how-to-guides/block-based-theme/block-based-themes-2-adding-blocks.md) diff --git a/docs/designers-developers/developers/tutorials/block-based-themes/block-based-themes-2-adding-blocks.md b/docs/how-to-guides/block-based-theme/block-based-themes-2-adding-blocks.md similarity index 100% rename from docs/designers-developers/developers/tutorials/block-based-themes/block-based-themes-2-adding-blocks.md rename to docs/how-to-guides/block-based-theme/block-based-themes-2-adding-blocks.md diff --git a/docs/designers-developers/developers/tutorials/block-tutorial/readme.md b/docs/how-to-guides/block-tutorial/README.md similarity index 89% rename from docs/designers-developers/developers/tutorials/block-tutorial/readme.md rename to docs/how-to-guides/block-tutorial/README.md index 42d72444e898e7..d16645fdf45e0e 100644 --- a/docs/designers-developers/developers/tutorials/block-tutorial/readme.md +++ b/docs/how-to-guides/block-tutorial/README.md @@ -4,6 +4,6 @@ The purpose of this tutorial is to step through the fundamentals of creating a n To follow along with this tutorial, you can [download the accompanying WordPress plugin](https://github.com/WordPress/gutenberg-examples) which includes all of the examples for you to try on your own site. At each step along the way, experiment by modifying the examples with your own ideas, and observe the effects they have on the block's behavior. -Code snippets are provided in two formats "ES5" and "ESNext". ES5 refers to "classic" JavaScript (ECMAScript 5), while ESNext refers to the next versions of the language standard, plus JSX syntax. You can change between them using tabs found above each code example. Using ESNext, does require you to run [the JavaScript build step](/docs/designers-developers/developers/tutorials/javascript/js-build-setup/) to compile your code to a browser compatible format. +Code snippets are provided in two formats "ES5" and "ESNext". ES5 refers to "classic" JavaScript (ECMAScript 5), while ESNext refers to the next versions of the language standard, plus JSX syntax. You can change between them using tabs found above each code example. Using ESNext, does require you to run [the JavaScript build step](/docs/how-to-guides/javascript/js-build-setup/) to compile your code to a browser compatible format. Note that it is not required to use ESNext to create blocks or extend the editor, you can use classic JavaScript. However, once familiar with ESNext, developers find it is easier to read and write, thus most code examples you'll find use the ESNext syntax. diff --git a/docs/designers-developers/developers/tutorials/block-tutorial/applying-styles-with-stylesheets.md b/docs/how-to-guides/block-tutorial/applying-styles-with-stylesheets.md similarity index 96% rename from docs/designers-developers/developers/tutorials/block-tutorial/applying-styles-with-stylesheets.md rename to docs/how-to-guides/block-tutorial/applying-styles-with-stylesheets.md index 5df98a568fbcdd..c65d2ec46f8bce 100644 --- a/docs/designers-developers/developers/tutorials/block-tutorial/applying-styles-with-stylesheets.md +++ b/docs/how-to-guides/block-tutorial/applying-styles-with-stylesheets.md @@ -130,6 +130,9 @@ function gutenberg_examples_02_register_block() { filemtime( plugin_dir_path( __FILE__ ) . 'style.css' ) ); + // Allow inlining small stylesheets on the frontend if possible. + wp_style_add_data( 'gutenberg-examples-02', 'path', dirname( __FILE__ ) . '/style.css' ); + register_block_type( 'gutenberg-examples/example-02-stylesheets', array( 'apiVersion' => 2, 'style' => 'gutenberg-examples-02', diff --git a/docs/designers-developers/developers/tutorials/block-tutorial/block-controls-toolbar-and-sidebar.md b/docs/how-to-guides/block-tutorial/block-controls-toolbar-and-sidebar.md similarity index 97% rename from docs/designers-developers/developers/tutorials/block-tutorial/block-controls-toolbar-and-sidebar.md rename to docs/how-to-guides/block-tutorial/block-controls-toolbar-and-sidebar.md index fe4dfe67d0f365..957104508fdd2a 100644 --- a/docs/designers-developers/developers/tutorials/block-tutorial/block-controls-toolbar-and-sidebar.md +++ b/docs/how-to-guides/block-tutorial/block-controls-toolbar-and-sidebar.md @@ -4,7 +4,7 @@ To simplify block customization and ensure a consistent experience for users, th ## Block Toolbar -![Screenshot of the rich text toolbar applied to a Paragraph block inside the block editor](https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/assets/toolbar-text.png) +![Screenshot of the rich text toolbar applied to a Paragraph block inside the block editor](https://raw.githubusercontent.com/WordPress/gutenberg/HEAD/docs/assets/toolbar-text.png) When the user selects a block, a number of control buttons may be shown in a toolbar above the selected block. Some of these block-level controls are included automatically if the editor is able to transform the block to another type, or if the focused element is a RichText component. @@ -194,7 +194,7 @@ Note that `BlockControls` is only visible when the block is currently selected a ## Inspector -![Screenshot of the inspector panel focused on the settings for a Paragraph block](https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/assets/inspector.png) +![Screenshot of the inspector panel focused on the settings for a Paragraph block](https://raw.githubusercontent.com/WordPress/gutenberg/HEAD/docs/assets/inspector.png) The Settings Sidebar is used to display less-often-used settings or settings that require more screen space. The Settings Sidebar should be used for **block-level settings only**. diff --git a/docs/designers-developers/developers/tutorials/block-tutorial/creating-dynamic-blocks.md b/docs/how-to-guides/block-tutorial/creating-dynamic-blocks.md similarity index 89% rename from docs/designers-developers/developers/tutorials/block-tutorial/creating-dynamic-blocks.md rename to docs/how-to-guides/block-tutorial/creating-dynamic-blocks.md index 4f6d2c2557d5f7..bcd7fc023eba81 100644 --- a/docs/designers-developers/developers/tutorials/block-tutorial/creating-dynamic-blocks.md +++ b/docs/how-to-guides/block-tutorial/creating-dynamic-blocks.md @@ -5,11 +5,11 @@ Dynamic blocks are blocks that build their structure and content on the fly when There are two primary uses for dynamic blocks: 1. Blocks where content should change even if a post has not been updated. One example from WordPress itself is the Latest Posts block. This block will update everywhere it is used when a new post is published. -2. Blocks where updates to the code (HTML, CSS, JS) should be immediately shown on the front end of the website. For example, if you update the structure of a block by adding a new class, adding an HTML element, or changing the layout in any other way, using a dynamic block ensures those changes are applied immediately on all occurrences of that block across the site. (If a dynamic block is not used then when block code is updated Guterberg's [validation process](/docs/designers-developers/developers/block-api/block-edit-save.md#validation) generally applies, causing users to see the validation message, "This block appears to have been modified externally"). +2. Blocks where updates to the code (HTML, CSS, JS) should be immediately shown on the front end of the website. For example, if you update the structure of a block by adding a new class, adding an HTML element, or changing the layout in any other way, using a dynamic block ensures those changes are applied immediately on all occurrences of that block across the site. (If a dynamic block is not used then when block code is updated Guterberg's [validation process](/docs/reference-guides/block-api/block-edit-save.md#validation) generally applies, causing users to see the validation message, "This block appears to have been modified externally"). -For many dynamic blocks, the `save` callback function should be returned as `null`, which tells the editor to save only the [block attributes](/docs/designers-developers/developers/block-api/block-attributes.md) to the database. These attributes are then passed into the server-side rendering callback, so you can decide how to display the block on the front end of your site. When you return `null`, the editor will skip the block markup validation process, avoiding issues with frequently-changing markup. +For many dynamic blocks, the `save` callback function should be returned as `null`, which tells the editor to save only the [block attributes](/docs/reference-guides/block-api/block-attributes.md) to the database. These attributes are then passed into the server-side rendering callback, so you can decide how to display the block on the front end of your site. When you return `null`, the editor will skip the block markup validation process, avoiding issues with frequently-changing markup. -If you are using [InnerBlocks](/docs/designers-developers/developers/tutorials/block-tutorial/nested-blocks-inner-blocks.md) in a dynamic block you will need to save the `InnerBlocks` in the `save` callback function using `` +If you are using [InnerBlocks](/docs/how-to-guides/block-tutorial/nested-blocks-inner-blocks.md) in a dynamic block you will need to save the `InnerBlocks` in the `save` callback function using `` You can also save an HTML representation of the block. If you provide a server-side rendering callback, this HTML will be replaced with the output of your callback, but will be rendered if your block is deactivated or your render callback is removed. @@ -224,4 +224,4 @@ registerBlockType( 'gutenberg-examples/example-dynamic', { ``` {% end %} -Note that this code uses the `wp-server-side-render` package but not `wp-data`. Make sure to update the dependencies in the PHP code. You can use wp-scripts and ESNext setup for auto dependencies (see the [gutenberg-examples repo](https://github.com/WordPress/gutenberg-examples/tree/master/01-basic-esnext) for PHP code setup). +Note that this code uses the `wp-server-side-render` package but not `wp-data`. Make sure to update the dependencies in the PHP code. You can use wp-scripts and ESNext setup for auto dependencies (see the [gutenberg-examples repo](https://github.com/WordPress/gutenberg-examples/tree/HEAD/01-basic-esnext) for PHP code setup). diff --git a/docs/designers-developers/developers/tutorials/block-tutorial/generate-blocks-with-wp-cli.md b/docs/how-to-guides/block-tutorial/generate-blocks-with-wp-cli.md similarity index 54% rename from docs/designers-developers/developers/tutorials/block-tutorial/generate-blocks-with-wp-cli.md rename to docs/how-to-guides/block-tutorial/generate-blocks-with-wp-cli.md index 74a9921a11f5f9..b2b4c9efb89308 100644 --- a/docs/designers-developers/developers/tutorials/block-tutorial/generate-blocks-with-wp-cli.md +++ b/docs/how-to-guides/block-tutorial/generate-blocks-with-wp-cli.md @@ -2,6 +2,6 @@ ## WARNING -**Deprecated:** It is not no longer recommended to use WP-CLI or create-guten-block to generate block scaffolding. +**Deprecated:** It is no longer recommended to use WP-CLI or create-guten-block to generate block scaffolding. -The official script to generate a block is the new [@wordpress/create-block](/packages/create-block/README.md) package. This package follows the new block directory guidelines, and creates the proper block, environment, and standards set by the project. See the new [Create a Block tutorial](/docs/designers-developers/developers/tutorials/create-block/readme.md) for a complete walk-through. +The official script to generate a block is the new [@wordpress/create-block](/packages/create-block/README.md) package. This package follows the new block directory guidelines, and creates the proper block, environment, and standards set by the project. See the new [Create a Block tutorial](/docs/getting-started/tutorials/create-block/README.md) for a complete walk-through. diff --git a/docs/designers-developers/developers/tutorials/block-tutorial/introducing-attributes-and-editable-fields.md b/docs/how-to-guides/block-tutorial/introducing-attributes-and-editable-fields.md similarity index 91% rename from docs/designers-developers/developers/tutorials/block-tutorial/introducing-attributes-and-editable-fields.md rename to docs/how-to-guides/block-tutorial/introducing-attributes-and-editable-fields.md index e3696634992eb4..8da80032db9252 100644 --- a/docs/designers-developers/developers/tutorials/block-tutorial/introducing-attributes-and-editable-fields.md +++ b/docs/how-to-guides/block-tutorial/introducing-attributes-and-editable-fields.md @@ -18,7 +18,7 @@ One challenge of maintaining the representation of a block as a JavaScript objec }, ``` -When registering a new block type, the `attributes` property describes the shape of the attributes object you'd like to receive in the `edit` and `save` functions. Each value is a [source function](/docs/designers-developers/developers/block-api/block-attributes.md) to find the desired value from the markup of the block. +When registering a new block type, the `attributes` property describes the shape of the attributes object you'd like to receive in the `edit` and `save` functions. Each value is a [source function](/docs/reference-guides/block-api/block-attributes.md) to find the desired value from the markup of the block. In the code snippet above, when loading the editor, the `content` value will be extracted from the HTML of the paragraph element in the saved post's markup. @@ -26,7 +26,7 @@ In the code snippet above, when loading the editor, the `content` value will be Earlier examples used the `createElement` function to create DOM nodes, but it's also possible to encapsulate this behavior into "components". This abstraction helps you share common behaviors and hide complexity in self-contained units. -There are a number of [components available](/docs/designers-developers/developers/packages/packages-editor.md#components) to use in implementing your blocks. You can see one such component in the code below: the [`RichText` component](/docs/designers-developers/developers/packages/packages-editor.md#richtext) is part of the `wp-editor` package. +There are a number of [components available](/docs/reference-guides/packages/packages-editor.md#components) to use in implementing your blocks. You can see one such component in the code below: the [`RichText` component](/docs/reference-guides/packages/packages-editor.md#richtext) is part of the `wp-editor` package. The `RichText` component can be considered as a super-powered `textarea` element, enabling rich content editing including bold, italics, hyperlinks, etc. diff --git a/docs/designers-developers/developers/tutorials/block-tutorial/nested-blocks-inner-blocks.md b/docs/how-to-guides/block-tutorial/nested-blocks-inner-blocks.md similarity index 91% rename from docs/designers-developers/developers/tutorials/block-tutorial/nested-blocks-inner-blocks.md rename to docs/how-to-guides/block-tutorial/nested-blocks-inner-blocks.md index f7f46d6c71bec8..744aa7f2a89e28 100644 --- a/docs/designers-developers/developers/tutorials/block-tutorial/nested-blocks-inner-blocks.md +++ b/docs/how-to-guides/block-tutorial/nested-blocks-inner-blocks.md @@ -1,6 +1,6 @@ # Nested Blocks: Using InnerBlocks -You can create a single block that nests other blocks using the [InnerBlocks](https://github.com/WordPress/gutenberg/tree/master/packages/block-editor/src/components/inner-blocks/README.md) component. This is used in the Columns block, Social Links block, or any block you want to contain other blocks. +You can create a single block that nests other blocks using the [InnerBlocks](https://github.com/WordPress/gutenberg/tree/HEAD/packages/block-editor/src/components/inner-blocks/README.md) component. This is used in the Columns block, Social Links block, or any block you want to contain other blocks. Note: A single block can only contain one `InnerBlock` component. @@ -144,7 +144,7 @@ const MY_TEMPLATE = [ ``` {% end %} -Use the `templateLock` property to lock down the template. Using `all` locks the template complete, no changes can be made. Using `insert` prevents additional blocks to be inserted, but existing blocks can be reordered. See [templateLock documentation](https://github.com/WordPress/gutenberg/tree/master/packages/block-editor/src/components/inner-blocks/README.md#templatelock) for additional information. +Use the `templateLock` property to lock down the template. Using `all` locks the template complete, no changes can be made. Using `insert` prevents additional blocks to be inserted, but existing blocks can be reordered. See [templateLock documentation](https://github.com/WordPress/gutenberg/tree/HEAD/packages/block-editor/src/components/inner-blocks/README.md#templatelock) for additional information. ### Post Template @@ -165,7 +165,7 @@ add_action( 'init', function() { ## Parent-Child InnerBlocks -A common pattern for using InnerBlocks is to create a custom block that will be included only in the InnerBlocks. An example of this is the Columns block, that creates a single parent block called `columns` and then creates an child block called `column`. The parent block is defined to only allow the child blocks. See [Column code for reference](https://github.com/WordPress/gutenberg/tree/master/packages/block-library/src/column). +A common pattern for using InnerBlocks is to create a custom block that will be included only in the InnerBlocks. An example of this is the Columns block, that creates a single parent block called `columns` and then creates an child block called `column`. The parent block is defined to only allow the child blocks. See [Column code for reference](https://github.com/WordPress/gutenberg/tree/HEAD/packages/block-library/src/column). When defining a child block, use the `parent` block setting to define which block is the parent. This prevents the block showing in the inserter outside of the InnerBlock it is defined for. diff --git a/docs/designers-developers/developers/tutorials/block-tutorial/writing-your-first-block-type.md b/docs/how-to-guides/block-tutorial/writing-your-first-block-type.md similarity index 92% rename from docs/designers-developers/developers/tutorials/block-tutorial/writing-your-first-block-type.md rename to docs/how-to-guides/block-tutorial/writing-your-first-block-type.md index 53a73d7c5d7e80..55faf6d69f7571 100644 --- a/docs/designers-developers/developers/tutorials/block-tutorial/writing-your-first-block-type.md +++ b/docs/how-to-guides/block-tutorial/writing-your-first-block-type.md @@ -36,9 +36,9 @@ function gutenberg_examples_01_register_block() { add_action( 'init', 'gutenberg_examples_01_register_block' ); ``` -Note the above example, shows using the [wp-scripts build step](/docs/designers-developers/developers/tutorials/javascript/js-build-setup/) that automatically sets dependencies and versions the file. +Note the above example, shows using the [wp-scripts build step](/docs/how-to-guides/javascript/js-build-setup/) that automatically sets dependencies and versions the file. -If you were using the ES5 code, you would specify `array( 'wp-blocks', 'wp-element' )` as the dependency array. See the [example 01](https://github.com/WordPress/gutenberg-examples/blob/master/01-basic/index.php) in Gutenberg Examples repository for full syntax. +If you were using the ES5 code, you would specify `array( 'wp-blocks', 'wp-element' )` as the dependency array. See the [example 01](https://github.com/WordPress/gutenberg-examples/blob/HEAD/01-basic/index.php) in Gutenberg Examples repository for full syntax. - __`wp-blocks`__ includes block type registration and related functions - __`wp-element`__ includes the [WordPress Element abstraction](/packages/element/README.md) for describing the structure of your blocks @@ -123,7 +123,7 @@ registerBlockType( 'gutenberg-examples/example-01-basic-esnext', { _By now you should be able to see `Hello World, step 1 (from the editor).` in the admin side and `Hello World, step 1 (from the frontend).` on the frontend side._ -Once a block is registered, you should immediately see that it becomes available as an option in the editor inserter dialog, using values from `title`, `icon`, and `category` to organize its display. You can choose an icon from any included in the built-in [Dashicons icon set](https://developer.wordpress.org/resource/dashicons/), or provide a [custom svg element](/docs/designers-developers/developers/block-api/block-registration.md#icon-optional). +Once a block is registered, you should immediately see that it becomes available as an option in the editor inserter dialog, using values from `title`, `icon`, and `category` to organize its display. You can choose an icon from any included in the built-in [Dashicons icon set](https://developer.wordpress.org/resource/dashicons/), or provide a [custom svg element](/docs/reference-guides/block-api/block-registration.md#icon-optional). A block name must be prefixed with a namespace specific to your plugin. This helps prevent conflicts when more than one plugin registers a block with the same name. In this example, the namespace is `gutenberg-examples`. diff --git a/docs/designers-developers/designers/README.md b/docs/how-to-guides/designers/README.md similarity index 100% rename from docs/designers-developers/designers/README.md rename to docs/how-to-guides/designers/README.md diff --git a/docs/designers-developers/designers/animation.md b/docs/how-to-guides/designers/animation.md similarity index 100% rename from docs/designers-developers/designers/animation.md rename to docs/how-to-guides/designers/animation.md diff --git a/docs/designers-developers/designers/assets/advanced-settings-do.png b/docs/how-to-guides/designers/assets/advanced-settings-do.png similarity index 100% rename from docs/designers-developers/designers/assets/advanced-settings-do.png rename to docs/how-to-guides/designers/assets/advanced-settings-do.png diff --git a/docs/designers-developers/designers/assets/block-controls-do.png b/docs/how-to-guides/designers/assets/block-controls-do.png similarity index 100% rename from docs/designers-developers/designers/assets/block-controls-do.png rename to docs/how-to-guides/designers/assets/block-controls-do.png diff --git a/docs/designers-developers/designers/assets/block-controls-dont.png b/docs/how-to-guides/designers/assets/block-controls-dont.png similarity index 100% rename from docs/designers-developers/designers/assets/block-controls-dont.png rename to docs/how-to-guides/designers/assets/block-controls-dont.png diff --git a/docs/designers-developers/designers/assets/block-descriptions-do.png b/docs/how-to-guides/designers/assets/block-descriptions-do.png similarity index 100% rename from docs/designers-developers/designers/assets/block-descriptions-do.png rename to docs/how-to-guides/designers/assets/block-descriptions-do.png diff --git a/docs/designers-developers/designers/assets/block-descriptions-dont.png b/docs/how-to-guides/designers/assets/block-descriptions-dont.png similarity index 100% rename from docs/designers-developers/designers/assets/block-descriptions-dont.png rename to docs/how-to-guides/designers/assets/block-descriptions-dont.png diff --git a/docs/designers-developers/designers/assets/blocks-do.png b/docs/how-to-guides/designers/assets/blocks-do.png similarity index 100% rename from docs/designers-developers/designers/assets/blocks-do.png rename to docs/how-to-guides/designers/assets/blocks-do.png diff --git a/docs/designers-developers/designers/assets/blocks-dont.png b/docs/how-to-guides/designers/assets/blocks-dont.png similarity index 100% rename from docs/designers-developers/designers/assets/blocks-dont.png rename to docs/how-to-guides/designers/assets/blocks-dont.png diff --git a/docs/designers-developers/designers/assets/placeholder-do.png b/docs/how-to-guides/designers/assets/placeholder-do.png similarity index 100% rename from docs/designers-developers/designers/assets/placeholder-do.png rename to docs/how-to-guides/designers/assets/placeholder-do.png diff --git a/docs/designers-developers/designers/assets/placeholder-dont.png b/docs/how-to-guides/designers/assets/placeholder-dont.png similarity index 100% rename from docs/designers-developers/designers/assets/placeholder-dont.png rename to docs/how-to-guides/designers/assets/placeholder-dont.png diff --git a/docs/designers-developers/designers/block-design.md b/docs/how-to-guides/designers/block-design.md similarity index 83% rename from docs/designers-developers/designers/block-design.md rename to docs/how-to-guides/designers/block-design.md index b1f73d30c959d1..c054e34da1fa7b 100644 --- a/docs/designers-developers/designers/block-design.md +++ b/docs/how-to-guides/designers/block-design.md @@ -15,6 +15,12 @@ Since the block itself represents what will actually appear on the site, interac Basic block settings won’t always make sense in the context of the placeholder/content UI. As a secondary option, options that are critical to the functionality of a block can live in the block toolbar. The Block Toolbar is still highly contextual and visible on all screen sizes. One notable constraint with the Block Toolbar is that it is icon-based UI, so any controls that live in the Block Toolbar need to be ones that can effectively be communicated via an icon or icon group. +### Group Block Toolbar controls with related items + +The Block Toolbar groups controls in segments, hierarchically. The first segment contains block type controls, such as the block switcher, the drag handle, and the mover control. The second group contains common and specific block tools that affect the entire block, followed by inline formatting, and the "More" menu. Optionally "Meta" or "Other" groups can separate some tools in their own segment. + +![A screenshot showing examples of block toolbar segment groupings.](https://make.wordpress.org/design/files/2021/03/docs_block-toolbar-structure.png) + ### The Settings Sidebar should only be used for advanced, tertiary controls The Settings Sidebar is not visible by default on a small / mobile screen, and may also be collapsed in a desktop view. Therefore, it should not be relied on for anything that is necessary for the basic operation of the block. Pick good defaults, make important actions available in the block toolbar, and think of the Settings Sidebar as something that most users should not need to open. @@ -27,7 +33,7 @@ Each Settings Sidebar comes with an "Advanced" section by default. This area hou Setup states, sometimes referred to as "placeholders", can be used to walk users through an initial process before showing the live preview state of the block. The setup process gathers information from the user that is needed to render the block. A block’s setup state is indicated with a grey background to provide clear differentiation for the user. Not all blocks have setup states — for example, the Paragraph block. -![An example of a gallery block’s setup state on a grey background](https://make.wordpress.org/design/files/2018/12/gallery-setup.png) +![An example of an image block’s setup state on a grey background](https://make.wordpress.org/design/files/2021/03/docs__gallery-setup-state.png) A setup state is **not** necessary if: @@ -52,6 +58,12 @@ In most cases, a block’s setup state is only shown once and then further custo ## Do's and Don'ts +### Block Toolbar + +Group toolbar controls in logical segments. Don't add a segment for each. + +![A screenshot comparing a block toolbar with good vs. bad toolbar segment groupings.](https://make.wordpress.org/design/files/2021/03/docs__block-toolbar-do-dont.png) + ### Block Identification A block should have a straightforward, short name so users can easily find it in the block library. A block named "YouTube" is easy to find and understand. The same block, named "Embedded Video (YouTube)", would be less clear and harder to find in the block library. @@ -64,11 +76,11 @@ When referring to a block in documentation or UI, use title case for the block t Blocks should have an identifying icon, ideally using a single color. Try to avoid using the same icon used by an existing block. The core block icons are based on [Material Design Icons](https://material.io/tools/icons/). Look to that icon set, or to [Dashicons](https://developer.wordpress.org/resource/dashicons/) for style inspiration. -![A screenshot of the block library with concise block names](https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/designers/assets/blocks-do.png) +![A screenshot of the block library with concise block names](https://raw.githubusercontent.com/WordPress/gutenberg/HEAD/docs/how-to-guides/designers/assets/blocks-do.png) **Do:** Use concise block names. -![A screenshot of the block library with long, multi-line block names](https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/designers/assets/blocks-dont.png) +![A screenshot of the block library with long, multi-line block names](https://raw.githubusercontent.com/WordPress/gutenberg/HEAD/docs/how-to-guides/designers/assets/blocks-dont.png) **Don't:** Avoid long, multi-line block names. @@ -76,7 +88,7 @@ Avoid long, multi-line block names. Every block should include a description that clearly explains the block's function. The description will display in the Settings Sidebar. -You can add a description by using the description attribute in the [registerBlockType function](/docs/designers-developers/developers/block-api/block-registration.md). +You can add a description by using the description attribute in the [registerBlockType function](/docs/reference-guides/block-api/block-registration.md). Stick to a single imperative sentence with an action + subject format. Examples: @@ -84,11 +96,11 @@ Stick to a single imperative sentence with an action + subject format. Examples: - Introduce new sections and organize content to help visitors (and search engines) understand the structure of your content. - Create a bulleted or numbered list. -![A screenshot of a short block description](https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/designers/assets/block-descriptions-do.png) +![A screenshot of a short block description](https://raw.githubusercontent.com/WordPress/gutenberg/HEAD/docs/how-to-guides/designers/assets/block-descriptions-do.png) **Do:** Use a short, simple block description. -![A screenshot of a long block description that includes branding](https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/designers/assets/block-descriptions-dont.png) +![A screenshot of a long block description that includes branding](https://raw.githubusercontent.com/WordPress/gutenberg/HEAD/docs/how-to-guides/designers/assets/block-descriptions-dont.png) **Don't:** Avoid long descriptions and branding. @@ -96,11 +108,11 @@ Avoid long descriptions and branding. If your block requires a user to configure some options before you can display it, you should provide an instructive placeholder state. -![A screenshot of the Gallery block's placeholder](https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/designers/assets/placeholder-do.png) +![A screenshot of the Gallery block's placeholder](https://raw.githubusercontent.com/WordPress/gutenberg/HEAD/docs/how-to-guides/designers/assets/placeholder-do.png) **Do:** Provide an instructive placeholder state. -![An example Gallery block placeholder but with intense, distracting colors and no instructions](https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/designers/assets/placeholder-dont.png) +![An example Gallery block placeholder but with intense, distracting colors and no instructions](https://raw.githubusercontent.com/WordPress/gutenberg/HEAD/docs/how-to-guides/designers/assets/placeholder-dont.png) **Don't:** Avoid branding and relying on the title alone to convey instructions. @@ -110,11 +122,11 @@ When unselected, your block should preview its content as closely to the front-e When selected, your block may surface additional options like input fields or buttons to configure the block directly, especially when they are necessary for basic operation. -![A Google Maps block with inline, always-accessible controls required for the block to function](https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/designers/assets/block-controls-do.png) +![A Google Maps block with inline, always-accessible controls required for the block to function](https://raw.githubusercontent.com/WordPress/gutenberg/HEAD/docs/how-to-guides/designers/assets/block-controls-do.png) **Do:** For controls that are essential for the operation of the block, provide them directly inside the block edit view. -![A Google Maps block with essential controls moved to the sidebar where they can be contextually hidden](https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/designers/assets/block-controls-dont.png) +![A Google Maps block with essential controls moved to the sidebar where they can be contextually hidden](https://raw.githubusercontent.com/WordPress/gutenberg/HEAD/docs/how-to-guides/designers/assets/block-controls-dont.png) **Don't:** Do not put controls that are essential to the block in the sidebar, otherwise the block will appear non-functional to mobile users or desktop users who have dismissed the sidebar. @@ -122,7 +134,7 @@ Do not put controls that are essential to the block in the sidebar, otherwise th The “Block” tab of the Settings Sidebar can contain additional block options and configuration. Keep in mind that a user can dismiss the sidebar and never use it. You should not put critical options in the Sidebar. -![A screenshot of the Paragraph block's advanced settings in the sidebar](https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/designers/assets/advanced-settings-do.png) +![A screenshot of the Paragraph block's advanced settings in the sidebar](https://raw.githubusercontent.com/WordPress/gutenberg/HEAD/docs/how-to-guides/designers/assets/advanced-settings-do.png) **Do:** Because the Drop Cap feature is not necessary for the basic operation of the block, you can put it to the Block tab as optional configuration. @@ -132,7 +144,7 @@ Check how your block looks, feels, and works on as many devices and screen sizes ### Support Gutenberg's dark background editor scheme -Check how your block looks with [dark backgrounds](/docs/designers-developers/developers/themes/theme-support.md#dark-backgrounds) in the editor. +Check how your block looks with [dark backgrounds](/docs/how-to-guides/themes/theme-support.md#dark-backgrounds) in the editor. ## Examples diff --git a/docs/designers-developers/designers/design-resources.md b/docs/how-to-guides/designers/design-resources.md similarity index 100% rename from docs/designers-developers/designers/design-resources.md rename to docs/how-to-guides/designers/design-resources.md diff --git a/docs/designers-developers/designers/user-interface.md b/docs/how-to-guides/designers/user-interface.md similarity index 100% rename from docs/designers-developers/designers/user-interface.md rename to docs/how-to-guides/designers/user-interface.md diff --git a/docs/designers-developers/developers/feature-flags.md b/docs/how-to-guides/feature-flags.md similarity index 100% rename from docs/designers-developers/developers/feature-flags.md rename to docs/how-to-guides/feature-flags.md diff --git a/docs/designers-developers/developers/tutorials/format-api/1-register-format.md b/docs/how-to-guides/format-api/1-register-format.md similarity index 100% rename from docs/designers-developers/developers/tutorials/format-api/1-register-format.md rename to docs/how-to-guides/format-api/1-register-format.md diff --git a/docs/designers-developers/developers/tutorials/format-api/2-toolbar-button.md b/docs/how-to-guides/format-api/2-toolbar-button.md similarity index 94% rename from docs/designers-developers/developers/tutorials/format-api/2-toolbar-button.md rename to docs/how-to-guides/format-api/2-toolbar-button.md index 88840f1059020a..4d64c1e7dcee38 100644 --- a/docs/designers-developers/developers/tutorials/format-api/2-toolbar-button.md +++ b/docs/how-to-guides/format-api/2-toolbar-button.md @@ -1,6 +1,6 @@ # Add a Button to the Toolbar -Now that the format is available, the next step is to surface it to the UI. You can make use of the [`RichTextToolbarButton`](https://github.com/WordPress/gutenberg/tree/master/packages/block-editor/src/components/rich-text#richtexttoolbarbutton) component to extend the format toolbar. +Now that the format is available, the next step is to surface it to the UI. You can make use of the [`RichTextToolbarButton`](https://github.com/WordPress/gutenberg/tree/HEAD/packages/block-editor/src/components/rich-text#richtexttoolbarbutton) component to extend the format toolbar. Paste this code in `my-custom-format.js`: @@ -59,7 +59,7 @@ registerFormatType( Let's check that everything is working as expected. Reload the post/page and select a text block. Make sure that the new button was added to the format toolbar, it uses the [editor-code dashicon](https://developer.wordpress.org/resource/dashicons/#editor-code), and the hover text is what you set in the title: -![Toolbar with custom button](https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/assets/toolbar-with-custom-button.png) +![Toolbar with custom button](https://raw.githubusercontent.com/WordPress/gutenberg/HEAD/docs/assets/toolbar-with-custom-button.png) You may also want to check that upon clicking the button the `toggle format` message is shown in your browser's console. diff --git a/docs/designers-developers/developers/tutorials/format-api/3-apply-format.md b/docs/how-to-guides/format-api/3-apply-format.md similarity index 96% rename from docs/designers-developers/developers/tutorials/format-api/3-apply-format.md rename to docs/how-to-guides/format-api/3-apply-format.md index 53e72e3ceba18d..25dd678114eeb7 100644 --- a/docs/designers-developers/developers/tutorials/format-api/3-apply-format.md +++ b/docs/how-to-guides/format-api/3-apply-format.md @@ -71,4 +71,4 @@ The expected behavior is that the format will be toggled, meaning that the text Your browser may have already displayed the selection differently once the tag was applied, but you may want to use a special style of your own. You can use the `className` option in [`registerFormatType`](/packages/rich-text/README.md#registerFormatType) to target the new element by class name: if `className` is set, it'll be added to the new element. -That's it. This is all that is necessary to make a custom format available in the new editor. From here, you may want to check out other [tutorials](/docs/designers-developers/developers/tutorials/) or apply your new knowledge to your next plugin! +That's it. This is all that is necessary to make a custom format available in the new editor. From here, you may want to check out other [tutorials](/docs/getting-started/tutorials/) or apply your new knowledge to your next plugin! diff --git a/docs/designers-developers/developers/tutorials/format-api/README.md b/docs/how-to-guides/format-api/README.md similarity index 68% rename from docs/designers-developers/developers/tutorials/format-api/README.md rename to docs/how-to-guides/format-api/README.md index 3ecb76c07e0596..dfaafaf2206e54 100644 --- a/docs/designers-developers/developers/tutorials/format-api/README.md +++ b/docs/how-to-guides/format-api/README.md @@ -4,10 +4,10 @@ The purpose of this tutorial is to introduce you to the Format API. The Format A In WordPress lingo, a _format_ is a [HTML tag with text-level semantics](https://www.w3.org/TR/html5/textlevel-semantics.html#text-level-semantics-usage-summary) used to give some special meaning to a text selection. For example, in this tutorial, the button to be hooked into the format toolbar will let users wrap a particular text selection with the [`` HTML tag](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/samp). -If you are unfamiliar with how to work with WordPress plugins and JavaScript, you may want to check the [JavaScript Tutorial](/docs/designers-developers/developers/tutorials/javascript/readme.md) first. +If you are unfamiliar with how to work with WordPress plugins and JavaScript, you may want to check the [JavaScript Tutorial](/docs/how-to-guides/javascript/README.md) first. ## Table of Contents -1. [Register a new format](/docs/designers-developers/developers/tutorials/format-api/1-register-format.md) -2. [Add a button to the toolbar](/docs/designers-developers/developers/tutorials/format-api/2-toolbar-button.md) -3. [Apply the format when the button is clicked](/docs/designers-developers/developers/tutorials/format-api/3-apply-format.md) +1. [Register a new format](/docs/how-to-guides/format-api/1-register-format.md) +2. [Add a button to the toolbar](/docs/how-to-guides/format-api/2-toolbar-button.md) +3. [Apply the format when the button is clicked](/docs/how-to-guides/format-api/3-apply-format.md) diff --git a/docs/designers-developers/developers/internationalization.md b/docs/how-to-guides/internationalization.md similarity index 97% rename from docs/designers-developers/developers/internationalization.md rename to docs/how-to-guides/internationalization.md index 50bc9c12268d8a..65ad0e204b6803 100644 --- a/docs/designers-developers/developers/internationalization.md +++ b/docs/how-to-guides/internationalization.md @@ -270,3 +270,7 @@ Using `make-json` automatically names the file with the md5 hash, so it is ready You will need to set your WordPress installation to Esperanto language. Go to Settings > General and change your site language to Esperanto. With the language set, create a new post, add the block, and you will see the translations used. + +### Filtering Translations + +The outputs of the translation functions (`__()`, `_x()`, `_n()`, and `_nx()`) are filterable, see [i18n Filters](/docs/reference-guides/filters/i18n-filters.md) for full information. diff --git a/docs/designers-developers/developers/tutorials/javascript/readme.md b/docs/how-to-guides/javascript/README.md similarity index 51% rename from docs/designers-developers/developers/tutorials/javascript/readme.md rename to docs/how-to-guides/javascript/README.md index c0a80e1b3e20c7..b31b0fa4d9989b 100644 --- a/docs/designers-developers/developers/tutorials/javascript/readme.md +++ b/docs/how-to-guides/javascript/README.md @@ -10,11 +10,11 @@ The block editor introduced in WordPress 5.0 is written in JavaScript, with the ### Table of Contents -1. [Plugins Background](/docs/designers-developers/developers/tutorials/javascript/plugins-background.md) -2. [Loading JavaScript](/docs/designers-developers/developers/tutorials/javascript/loading-javascript.md) -3. [Extending the Block Editor](/docs/designers-developers/developers/tutorials/javascript/extending-the-block-editor.md) -4. [Troubleshooting](/docs/designers-developers/developers/tutorials/javascript/troubleshooting.md) -5. [JavaScript Versions and Building](/docs/designers-developers/developers/tutorials/javascript/versions-and-building.md) -6. [Scope your code](/docs/designers-developers/developers/tutorials/javascript/scope-your-code.md) -7. [JavaScript Build Step](/docs/designers-developers/developers/tutorials/javascript/js-build-setup.md) -8. [ESNext Syntax](/docs/designers-developers/developers/tutorials/javascript/esnext-js.md) +1. [Plugins Background](/docs/how-to-guides/javascript/plugins-background.md) +2. [Loading JavaScript](/docs/how-to-guides/javascript/loading-javascript.md) +3. [Extending the Block Editor](/docs/how-to-guides/javascript/extending-the-block-editor.md) +4. [Troubleshooting](/docs/how-to-guides/javascript/troubleshooting.md) +5. [JavaScript Versions and Building](/docs/how-to-guides/javascript/versions-and-building.md) +6. [Scope your code](/docs/how-to-guides/javascript/scope-your-code.md) +7. [JavaScript Build Step](/docs/how-to-guides/javascript/js-build-setup.md) +8. [ESNext Syntax](/docs/how-to-guides/javascript/esnext-js.md) diff --git a/docs/designers-developers/developers/tutorials/javascript/esnext-js.md b/docs/how-to-guides/javascript/esnext-js.md similarity index 100% rename from docs/designers-developers/developers/tutorials/javascript/esnext-js.md rename to docs/how-to-guides/javascript/esnext-js.md diff --git a/docs/designers-developers/developers/tutorials/javascript/extending-the-block-editor.md b/docs/how-to-guides/javascript/extending-the-block-editor.md similarity index 78% rename from docs/designers-developers/developers/tutorials/javascript/extending-the-block-editor.md rename to docs/how-to-guides/javascript/extending-the-block-editor.md index 395565c06478cb..0a32b380318a82 100644 --- a/docs/designers-developers/developers/tutorials/javascript/extending-the-block-editor.md +++ b/docs/how-to-guides/javascript/extending-the-block-editor.md @@ -1,6 +1,6 @@ # Extending the Block Editor -Let's look at using the [Block Style Variation example](/docs/designers-developers/developers/filters/block-filters.md#block-style-variations) to extend the editor. This example allows you to add your own custom CSS class name to any core block type. +Let's look at using the [Block Style Variation example](/docs/reference-guides/filters/block-filters.md#block-style-variations) to extend the editor. This example allows you to add your own custom CSS class name to any core block type. Replace the existing `console.log()` code in your `myguten.js` file with: @@ -30,7 +30,7 @@ add_action( 'enqueue_block_editor_assets', 'myguten_enqueue' ); The last argument in the `wp_enqueue_script()` function is an array of dependencies. WordPress makes packages available under the `wp` namespace. In the example, you use `wp.blocks` to access the items that the blocks package exports (in this case the `registerBlockStyle()` function). -See [Packages](/docs/designers-developers/developers/packages.md) for list of available packages and what objects they export. +See [Packages](/docs/reference-guides/packages.md) for list of available packages and what objects they export. After you have updated both JavaScript and PHP files, go to the block editor and create a new post. @@ -39,7 +39,7 @@ Add a quote block, and in the right sidebar under Styles, you will see your new Click the Fancy Quote to select and apply that style to your quote block: -![Fancy Quote Style in Inspector](https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/assets/fancy-quote-in-inspector.png) +![Fancy Quote Style in Inspector](https://raw.githubusercontent.com/WordPress/gutenberg/HEAD/docs/assets/fancy-quote-in-inspector.png) Even if you Preview or Publish the post you will not see a visible change. However, if you look at the source, you will see the `is-style-fancy-quote` class name is now attached to your quote block. @@ -63,4 +63,4 @@ add_action( 'enqueue_block_assets', 'myguten_stylesheet' ); Now when you view in the editor and publish, you will see your Fancy Quote style, a delicious tomato color text: -![Fancy Quote with Style](https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/assets/fancy-quote-with-style.png) +![Fancy Quote with Style](https://raw.githubusercontent.com/WordPress/gutenberg/HEAD/docs/assets/fancy-quote-with-style.png) diff --git a/docs/designers-developers/developers/tutorials/javascript/js-build-setup.md b/docs/how-to-guides/javascript/js-build-setup.md similarity index 92% rename from docs/designers-developers/developers/tutorials/javascript/js-build-setup.md rename to docs/how-to-guides/javascript/js-build-setup.md index a1d3c9183aae7f..15bcf85f4914c4 100644 --- a/docs/designers-developers/developers/tutorials/javascript/js-build-setup.md +++ b/docs/how-to-guides/javascript/js-build-setup.md @@ -2,9 +2,9 @@ ESNext is JavaScript written using syntax and features only available in a version newer than browser support—the support browser versions is referred to as ECMAScript 5 (ES5). [JSX](https://reactjs.org/docs/introducing-jsx.html) is a custom syntax extension to JavaScript, created by React project, that allows you to write JavaScript using a familiar HTML tag-like syntax. -See the [ESNext syntax documentation](/docs/designers-developers/developers/tutorials/javascript/esnext-js.md) for explanation and examples about common code differences between standard JavaScript and ESNext. +See the [ESNext syntax documentation](/docs/how-to-guides/javascript/esnext-js.md) for explanation and examples about common code differences between standard JavaScript and ESNext. -Let's set up your development environment to use these syntaxes, we'll cover development for your plugin to work with the Gutenberg project (ie: the block editor). If you want to develop on Gutenberg itself, see the [Getting Started](/docs/contributors/getting-started.md) documentation. +Let's set up your development environment to use these syntaxes, we'll cover development for your plugin to work with the Gutenberg project (ie: the block editor). If you want to develop on Gutenberg itself, see the [Getting Started](/docs/contributors/code/getting-started-with-code-contribution.md) documentation. Browsers cannot interpret or run ESNext and JSX syntaxes, so we must use a transformation step to convert these syntaxes to code that browsers can understand. @@ -34,7 +34,7 @@ First, you need to set up Node.js for your development environment. The steps re - macOS: `brew install node` - Windows: `choco install node` -If you are not using a package manager, see the [developer environment setup documentation](/docs/designers-developers/developers/tutorials/devenv/readme.md) for setting up Node using nvm, or see the official [Node.js download page](https://nodejs.org/en/download/) for installers and binaries. +If you are not using a package manager, see the [developer environment setup documentation](/docs/getting-started/tutorials/devenv/README.md) for setting up Node using nvm, or see the official [Node.js download page](https://nodejs.org/en/download/) for installers and binaries. **Note:** The build tools and process occur on the command-line, so basic familiarity using a terminal application is required. Some text editors have a terminal built-in that is fine to use; Visual Studio Code and PhpStorm are two popular options. @@ -125,7 +125,7 @@ To configure npm to run a script, you use the scripts section in `package.json` You can then run the build using: `npm run build`. -After the build finishes, you will see the built file created at `build/index.js`. Enqueue this file in the admin screen as you would any JavaScript in WordPress, see [loading JavaScript step in this tutorial](/docs/designers-developers/developers/tutorials/javascript/loading-javascript.md), and the block will load in the editor. +After the build finishes, you will see the built file created at `build/index.js`. Enqueue this file in the admin screen as you would any JavaScript in WordPress, see [loading JavaScript step in this tutorial](/docs/how-to-guides/javascript/loading-javascript.md), and the block will load in the editor. ## Development Mode diff --git a/docs/designers-developers/developers/tutorials/javascript/loading-javascript.md b/docs/how-to-guides/javascript/loading-javascript.md similarity index 95% rename from docs/designers-developers/developers/tutorials/javascript/loading-javascript.md rename to docs/how-to-guides/javascript/loading-javascript.md index f48775df5782d9..c029d198c08f2e 100644 --- a/docs/designers-developers/developers/tutorials/javascript/loading-javascript.md +++ b/docs/how-to-guides/javascript/loading-javascript.md @@ -28,7 +28,7 @@ We'll check the JavaScript console in your browser's Developer Tools, to see if If your code is registered and enqueued correctly, you should see a message in your console: -![Console Log Message Success](https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/assets/js-tutorial-console-log-success.png) +![Console Log Message Success](https://raw.githubusercontent.com/WordPress/gutenberg/HEAD/docs/assets/js-tutorial-console-log-success.png) **Note for Theme Developers:** The above method of enqueuing is used for plugins. If you are extending the block editor for your theme there is a minor difference, you will use the `get_template_directory_uri()` function instead of `plugins_url()`. So for a theme, the enqueue example is: diff --git a/docs/designers-developers/developers/tutorials/javascript/plugins-background.md b/docs/how-to-guides/javascript/plugins-background.md similarity index 100% rename from docs/designers-developers/developers/tutorials/javascript/plugins-background.md rename to docs/how-to-guides/javascript/plugins-background.md diff --git a/docs/designers-developers/developers/tutorials/javascript/scope-your-code.md b/docs/how-to-guides/javascript/scope-your-code.md similarity index 100% rename from docs/designers-developers/developers/tutorials/javascript/scope-your-code.md rename to docs/how-to-guides/javascript/scope-your-code.md diff --git a/docs/designers-developers/developers/tutorials/javascript/troubleshooting.md b/docs/how-to-guides/javascript/troubleshooting.md similarity index 88% rename from docs/designers-developers/developers/tutorials/javascript/troubleshooting.md rename to docs/how-to-guides/javascript/troubleshooting.md index 442ecef42678dd..7fe4784bf30ab3 100644 --- a/docs/designers-developers/developers/tutorials/javascript/troubleshooting.md +++ b/docs/how-to-guides/javascript/troubleshooting.md @@ -19,7 +19,7 @@ To open the JavaScript console, find the correct key combination for your broswe Your first step in debugging should be to check the JavaScript console for any errors. Here is an example, which shows a syntax error on line 6: -![console error](https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/assets/js-tutorial-console-log-error.png) +![console error](https://raw.githubusercontent.com/WordPress/gutenberg/HEAD/docs/assets/js-tutorial-console-log-error.png) ### Display your message in console log @@ -55,13 +55,13 @@ If you are not seeing your changes, and no errors, check that your JavaScript fi If you do not see the file being loaded, double check the enqueue function is correct. You can also check your server logs to see if there is an error messages. -Add a test message to confirm your JavaScript is loading, add a `console.log("Here");` at the top of your code, and confirm the message is shown. If not, it is likely the file is not loading properly, [review the loading JavaScript page](/docs/designers-developers/developers/tutorials/javascript/loading-javascript.md) for details on enqueuing JavaScript properly. +Add a test message to confirm your JavaScript is loading, add a `console.log("Here");` at the top of your code, and confirm the message is shown. If not, it is likely the file is not loading properly, [review the loading JavaScript page](/docs/how-to-guides/javascript/loading-javascript.md) for details on enqueuing JavaScript properly. ## Confirm all dependencies are loading The console log will show an error if a dependency your JavaScript code uses has not been declared and loaded in the browser. In the JavaScript tutorial example, if `myguten.js` script is enqueued without declaring the `wp-blocks` dependency, the console log will show: - + You can correct by checking your `wp_enqueue_script` function includes all packages listed that are used: @@ -73,4 +73,4 @@ wp_enqueue_script( ); ``` -For automated dependency management, it is recommended to [use wp-scripts to build step your JavaScript](/docs/designers-developers/developers/tutorials/javascript/js-build-setup.md#dependency-management). +For automated dependency management, it is recommended to [use wp-scripts to build step your JavaScript](/docs/how-to-guides/javascript/js-build-setup.md#dependency-management). diff --git a/docs/designers-developers/developers/tutorials/javascript/versions-and-building.md b/docs/how-to-guides/javascript/versions-and-building.md similarity index 80% rename from docs/designers-developers/developers/tutorials/javascript/versions-and-building.md rename to docs/how-to-guides/javascript/versions-and-building.md index ccd02f71aca0b7..afe4c365b51d77 100644 --- a/docs/designers-developers/developers/tutorials/javascript/versions-and-building.md +++ b/docs/how-to-guides/javascript/versions-and-building.md @@ -10,6 +10,6 @@ Additionally, the ESNext code examples in the handbook include [JSX syntax](http For simplicity, the JavaScript tutorial uses the ES5 definition, without JSX. This code can run straight in your browser and does not require an additional build step. In many cases, it is perfectly fine to follow the same approach for simple plugins or experimenting. As your codebase grows in complexity it might be a good idea to switch to ESNext. You will find the majority of code and documentation across the block editor uses ESNext. -See the [JavaScript Build Setup documentation](/docs/designers-developers/developers/tutorials/javascript/js-build-setup.md) for setting up a development environment using ESNext syntax. +See the [JavaScript Build Setup documentation](/docs/how-to-guides/javascript/js-build-setup.md) for setting up a development environment using ESNext syntax. -See the [ESNext syntax documentation](/docs/designers-developers/developers/tutorials/javascript/esnext-js.md) for explanation and examples about common code differences between standard JavaScript and ESNext. +See the [ESNext syntax documentation](/docs/how-to-guides/javascript/esnext-js.md) for explanation and examples about common code differences between standard JavaScript and ESNext. diff --git a/docs/designers-developers/developers/tutorials/metabox/readme.md b/docs/how-to-guides/metabox/README.md similarity index 69% rename from docs/designers-developers/developers/tutorials/metabox/readme.md rename to docs/how-to-guides/metabox/README.md index a1e29fb2beeff2..a35a9edac92a3d 100644 --- a/docs/designers-developers/developers/tutorials/metabox/readme.md +++ b/docs/how-to-guides/metabox/README.md @@ -2,7 +2,7 @@ Prior to the block editor, custom meta boxes were used to extend the editor. With the new editor there are new ways to extend, giving more power to the developer and a better experience for the authors. Porting older custom meta boxes to one of these new methods is encouraged as to create a more unified and consistent experience for those using the editor. -The new block editor does support most existing meta boxes, see [this backward compatibility article](/docs/designers-developers/developers/backward-compatibility/meta-box.md) for more support details . +The new block editor does support most existing meta boxes, see [this backward compatibility article](/docs/reference-guides/backward-compatibility/meta-box.md) for more support details . Here are two mini-tutorials for creating similar functionality to meta boxes in the block editor. @@ -10,9 +10,9 @@ Here are two mini-tutorials for creating similar functionality to meta boxes in The first method is to use Blocks to store extra data with a post. The data is stored in a post meta field, similar to how meta boxes store information. -* [Store Post Meta with a Block](/docs/designers-developers/developers/tutorials/metabox/meta-block-1-intro.md) +* [Store Post Meta with a Block](/docs/how-to-guides/metabox/meta-block-1-intro.md) ## Sidebar Plugin -If you are interested in working with the post meta outside the editor, check out the [Sidebar Tutorial](/docs/designers-developers/developers/tutorials/plugin-sidebar-0/). +If you are interested in working with the post meta outside the editor, check out the [Sidebar Tutorial](/docs/how-to-guides/sidebar-tutorial/plugin-sidebar-0.md/). diff --git a/docs/how-to-guides/metabox/meta-block-1-intro.md b/docs/how-to-guides/metabox/meta-block-1-intro.md new file mode 100644 index 00000000000000..1b01662588eb75 --- /dev/null +++ b/docs/how-to-guides/metabox/meta-block-1-intro.md @@ -0,0 +1,17 @@ +# Store Post Meta with a Block + +Typically, blocks store their attribute values in the serialised block HTML. However, you can also create a block that saves its attribute values as post meta, which can be accessed programmatically anywhere in your template. + +In this short tutorial you will create one of these blocks, which will prompt a user for a single value, and save it as post meta. + +For background around the thinking of blocks as the interface, please see the [key concepts section](/docs/explanations/architecture/key-concepts.md) of the handbook. + +Before starting this tutorial, you will need a plugin to hold your code. Please take a look at the first two steps of [the JavaScript tutorial](/docs/how-to-guides/javascript/README.md) for information setting up a plugin. + +## Table of Contents + +1. [Register Meta Field](/docs/how-to-guides/metabox/meta-block-2-register-meta.md) +2. [Add Meta Block](/docs/how-to-guides/metabox/meta-block-3-add.md) +3. [Use Post Meta Data](/docs/how-to-guides/metabox/meta-block-4-use-data.md) +4. [Finishing Touches](/docs/how-to-guides/metabox/meta-block-5-finishing.md) + diff --git a/docs/designers-developers/developers/tutorials/metabox/meta-block-2-register-meta.md b/docs/how-to-guides/metabox/meta-block-2-register-meta.md similarity index 100% rename from docs/designers-developers/developers/tutorials/metabox/meta-block-2-register-meta.md rename to docs/how-to-guides/metabox/meta-block-2-register-meta.md diff --git a/docs/designers-developers/developers/tutorials/metabox/meta-block-3-add.md b/docs/how-to-guides/metabox/meta-block-3-add.md similarity index 88% rename from docs/designers-developers/developers/tutorials/metabox/meta-block-3-add.md rename to docs/how-to-guides/metabox/meta-block-3-add.md index bca448658d2c41..034de8a6c913a3 100644 --- a/docs/designers-developers/developers/tutorials/metabox/meta-block-3-add.md +++ b/docs/how-to-guides/metabox/meta-block-3-add.md @@ -1,6 +1,6 @@ # Create Meta Block -With the meta field registered in the previous step, next you will create a new block used to display the field value to the user. See the [Block Tutorial](/docs/designers-developers/developers/tutorials/block-tutorial/readme.md) for a deeper understanding of creating custom blocks. +With the meta field registered in the previous step, next you will create a new block used to display the field value to the user. See the [Block Tutorial](/docs/how-to-guides/block-tutorial/README.md) for a deeper understanding of creating custom blocks. For this block, you will use the TextControl component, which is similar to an HTML input text field. For additional components, check out the [Component Reference](/packages/components/README.md). @@ -136,6 +136,6 @@ add_action( 'enqueue_block_editor_assets', 'myguten_enqueue' ); You can now edit a draft post and add a Meta Block to the post. You will see your field that you can type a value in. When you save the post, either as a draft or published, the post meta value will be saved too. You can verify by saving and reloading your draft, the form will still be filled in on reload. -![Meta Block](https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/developers/tutorials/metabox/meta-block.png) +![Meta Block](https://raw.githubusercontent.com/WordPress/gutenberg/HEAD/docs/how-to-guides/metabox/meta-block.png) -You can now use the post meta data in a template, or another block. See next section for [using post meta data](/docs/designers-developers/developers/tutorials/metabox/meta-block-4-use-data.md). You could also confirm the data is saved by checking the database table `wp_postmeta` and confirm the new post id contains the new field data. +You can now use the post meta data in a template, or another block. See next section for [using post meta data](/docs/how-to-guides/metabox/meta-block-4-use-data.md). You could also confirm the data is saved by checking the database table `wp_postmeta` and confirm the new post id contains the new field data. diff --git a/docs/designers-developers/developers/tutorials/metabox/meta-block-4-use-data.md b/docs/how-to-guides/metabox/meta-block-4-use-data.md similarity index 100% rename from docs/designers-developers/developers/tutorials/metabox/meta-block-4-use-data.md rename to docs/how-to-guides/metabox/meta-block-4-use-data.md diff --git a/docs/designers-developers/developers/tutorials/metabox/meta-block-5-finishing.md b/docs/how-to-guides/metabox/meta-block-5-finishing.md similarity index 76% rename from docs/designers-developers/developers/tutorials/metabox/meta-block-5-finishing.md rename to docs/how-to-guides/metabox/meta-block-5-finishing.md index b8f41f104b8c8e..a5b02757ccaa98 100644 --- a/docs/designers-developers/developers/tutorials/metabox/meta-block-5-finishing.md +++ b/docs/how-to-guides/metabox/meta-block-5-finishing.md @@ -1,6 +1,6 @@ # Finishing Touches -One problem using a meta block is the block is easy for an author to forget, since it requires being added to each post. You solve this by using [block templates](/docs/designers-developers/developers/block-api/block-templates.md). A block template is a predefined list of block items per post type. Templates allow you to specify a default initial state for a post type. +One problem using a meta block is the block is easy for an author to forget, since it requires being added to each post. You solve this by using [block templates](/docs/reference-guides/block-api/block-templates.md). A block template is a predefined list of block items per post type. Templates allow you to specify a default initial state for a post type. For this example, you use a template to automatically insert the meta block at the top of a post. diff --git a/docs/designers-developers/developers/tutorials/metabox/meta-block.png b/docs/how-to-guides/metabox/meta-block.png similarity index 100% rename from docs/designers-developers/developers/tutorials/metabox/meta-block.png rename to docs/how-to-guides/metabox/meta-block.png diff --git a/docs/designers-developers/developers/tutorials/notices/README.md b/docs/how-to-guides/notices/README.md similarity index 85% rename from docs/designers-developers/developers/tutorials/notices/README.md rename to docs/how-to-guides/notices/README.md index 79422b412ccbf5..de9867307b5acd 100644 --- a/docs/designers-developers/developers/tutorials/notices/README.md +++ b/docs/how-to-guides/notices/README.md @@ -8,7 +8,7 @@ In the classic editor, notices hooked onto the `admin_notices` action can render In the classic editor, here's an example of the "Post draft updated" notice: -![Post draft updated in the classic editor](https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/developers/tutorials/notices/classic-editor-notice.png) +![Post draft updated in the classic editor](https://raw.githubusercontent.com/WordPress/gutenberg/HEAD/docs/how-to-guides/notices/classic-editor-notice.png) Producing an equivalent "Post draft updated" notice would require code like this: @@ -39,7 +39,7 @@ Importantly, the `admin_notices` hook allows a developer to render whatever HTML In the block editor, here's an example of the "Post published" notice: -![Post published in the block editor](https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/developers/tutorials/notices/block-editor-notice.png) +![Post published in the block editor](https://raw.githubusercontent.com/WordPress/gutenberg/HEAD/docs/how-to-guides/notices/block-editor-notice.png) Producing an equivalent "Post published" notice would require code like this: @@ -71,10 +71,10 @@ To better understand the specific code example above: * `wp.data.dispatch('core/notices')` accesses functionality registered to the block editor data store by the Notices package. * `createNotice()` is a function offered by the Notices package to register a new notice. The block editor reads from the notice data store in order to know which notices to display. -Check out the [_Loading JavaScript_](/docs/designers-developers/developers/tutorials/javascript/loading-javascript.md) tutorial for a primer on how to load your custom JavaScript into the block editor. +Check out the [_Loading JavaScript_](/docs/how-to-guides/javascript/loading-javascript.md) tutorial for a primer on how to load your custom JavaScript into the block editor. ## Learn More The block editor offers a complete API for generating notices. The official documentation is a great place to review what's possible. -For a full list of the available actions and selectors, refer to the [Notices Data Handbook](/docs/designers-developers/developers/data/data-core-notices.md) page. +For a full list of the available actions and selectors, refer to the [Notices Data Handbook](/docs/reference-guides/data/data-core-notices.md) page. diff --git a/docs/designers-developers/developers/tutorials/notices/block-editor-notice.png b/docs/how-to-guides/notices/block-editor-notice.png similarity index 100% rename from docs/designers-developers/developers/tutorials/notices/block-editor-notice.png rename to docs/how-to-guides/notices/block-editor-notice.png diff --git a/docs/designers-developers/developers/tutorials/notices/classic-editor-notice.png b/docs/how-to-guides/notices/classic-editor-notice.png similarity index 100% rename from docs/designers-developers/developers/tutorials/notices/classic-editor-notice.png rename to docs/how-to-guides/notices/classic-editor-notice.png diff --git a/docs/designers-developers/developers/platform/README.md b/docs/how-to-guides/platform/README.md similarity index 92% rename from docs/designers-developers/developers/platform/README.md rename to docs/how-to-guides/platform/README.md index e7ac946000f955..67e909a5cad60c 100644 --- a/docs/designers-developers/developers/platform/README.md +++ b/docs/how-to-guides/platform/README.md @@ -54,11 +54,11 @@ You can then add a scripts section to your package.json file, for example: You can then use `npm run build` to build your project with all the default webpack settings already configured, likewise for formating and linting. The `start` command is used for development mode. See [the scripts package](https://www.npmjs.com/package/@wordpress/scripts) for full documentation. -You can also play with the [Gutenberg Example #03](https://github.com/WordPress/gutenberg-examples/tree/master/03-editable-esnext) for a complete setup using the wp-scripts package. +You can also play with the [Gutenberg Example #03](https://github.com/WordPress/gutenberg-examples/tree/HEAD/03-editable-esnext) for a complete setup using the wp-scripts package. ## Block Editor The [`@wordpress/block-editor` package](https://developer.wordpress.org/block-editor/packages/packages-block-editor/) allows you to create and use standalone block editors. -You can learn more by reading the [tutorial "Building a custom block editor"](/docs/designers-developers/developers/platform/custom-block-editor/README.md). +You can learn more by reading the [tutorial "Building a custom block editor"](/docs/reference-guides/platform/custom-block-editor/README.md). diff --git a/docs/designers-developers/developers/platform/custom-block-editor/README.md b/docs/how-to-guides/platform/custom-block-editor/README.md similarity index 79% rename from docs/designers-developers/developers/platform/custom-block-editor/README.md rename to docs/how-to-guides/platform/custom-block-editor/README.md index adfb0dcc921474..65623044f31d53 100644 --- a/docs/designers-developers/developers/platform/custom-block-editor/README.md +++ b/docs/how-to-guides/platform/custom-block-editor/README.md @@ -1,6 +1,6 @@ # Building a custom block editor -The purpose of [this tutorial](/docs/designers-developers/developers/platform/custom-block-editor/tutorial.md) is to step through the fundamentals of creating a custom instance of a "block editor". +The purpose of [this tutorial](/docs/reference-guides/platform/custom-block-editor/tutorial.md) is to step through the fundamentals of creating a custom instance of a "block editor". ![alt text](https://wordpress.org/gutenberg/files/2020/03/editor.png "The Standalone Editor instance populated with example Blocks within a custom WP Admin page.") @@ -15,4 +15,4 @@ Code snippets are provided in "ESNext". ESNext refers to the next versions of th Note that it is not required to use ESNext to create blocks or extend the editor, you can use classic JavaScript. However, once familiar with ESNext, developers find it is easier to read and write, thus most code examples you'll find use the ESNext syntax. -* [Start custom block editor tutorial](/docs/designers-developers/developers/platform/custom-block-editor/tutorial.md) +* [Start custom block editor tutorial](/docs/reference-guides/platform/custom-block-editor/tutorial.md) diff --git a/docs/designers-developers/developers/platform/custom-block-editor/tutorial.md b/docs/how-to-guides/platform/custom-block-editor/tutorial.md similarity index 98% rename from docs/designers-developers/developers/platform/custom-block-editor/tutorial.md rename to docs/how-to-guides/platform/custom-block-editor/tutorial.md index 82866693efd2f2..62702baab2e2ca 100644 --- a/docs/designers-developers/developers/platform/custom-block-editor/tutorial.md +++ b/docs/how-to-guides/platform/custom-block-editor/tutorial.md @@ -45,7 +45,7 @@ With that in mind, let's start taking our first steps towards building this. ## Plugin setup and organization -Our custom editor is going to be built as a WordPress Plugin. To keep things simple. we'll call this `Standalone Block Editor Demo` because that is what is does. Nice! +Our custom editor is going to be built as a WordPress Plugin. To keep things simple. we'll call this `Standalone Block Editor Demo` because that is what it does. Nice! Let's take a look at our Plugin file structure: @@ -279,7 +279,7 @@ Here we are scaffolding the core of the editor's layout alongside a few speciali Let's examine these in more detail: * `` - enables the use of the ["Slot/Fill" - pattern](https://github.com/WordPress/gutenberg/blob/e38dbe958c04d8089695eb686d4f5caff2707505/docs/designers-developers/developers/slotfills/README.md) through our component tree. + pattern](/docs/reference-guides/slotfills/README.md) through our component tree. * `` - enables the use of [dropzones for drag and drop functionality](https://github.com/WordPress/gutenberg/tree/e38dbe958c04d8089695eb686d4f5caff2707505/packages/components/src/drop-zone). * `` - custom component. Provides a "snack bar" Notice that will be rendered if any messages are dispatched to `core/notices` store. * `
` - renders the static title "Standalone Block Editor" at the top of the @@ -377,7 +377,7 @@ For the purposes of our simple project these features allow us to: * Update the `blocks` state in memory on `onInput` by calling the hook setter `updateBlocks(blocks)`. * Handle basic persistence of blocks into `localStorage` using `onChange`. This is [fired when block updates are considered - "committed"](https://github.com/WordPress/gutenberg/tree/master/packages/block-editor/src/components/provider#onchange). + "committed"](https://github.com/WordPress/gutenberg/tree/HEAD/packages/block-editor/src/components/provider#onchange). It's also worth recalling that the component accepts a `settings` prop. This accepts the editor settings which we inlined as JSON within `init.php` earlier. This configures features such as custom colors, available image sizes and [much more](https://github.com/WordPress/gutenberg/tree/4c472c3443513d070a50ba1e96f3a476861447b3/packages/block-editor#SETTINGS_DEFAULTS). @@ -499,7 +499,7 @@ Without Slot/Fill this setup would be extremely difficult to achieve. Aside: [``](https://github.com/WordPress/gutenberg/blob/def076809d25e2ad680beda8b9205ab9dea45a0f/packages/block-editor/src/components/block-inspector/index.js) - itself actually renders a `Slot` for [``](https://github.com/WordPress/gutenberg/tree/master/packages/block-editor/src/components/inspector-controls + itself actually renders a `Slot` for [``](https://github.com/WordPress/gutenberg/tree/HEAD/packages/block-editor/src/components/inspector-controls ). This is what allows you [render a `` component inside the `edit()` definition for your block](https://github.com/WordPress/gutenberg/blob/def076809d25e2ad680beda8b9205ab9dea45a0f/packages/block-library/src/paragraph/edit.js#L127) and have it display within Gutenberg's sidebar. I recommend looking into this component diff --git a/docs/how-to-guides/sidebar-tutorial/plugin-sidebar-0.md b/docs/how-to-guides/sidebar-tutorial/plugin-sidebar-0.md new file mode 100644 index 00000000000000..fa33fb682c874f --- /dev/null +++ b/docs/how-to-guides/sidebar-tutorial/plugin-sidebar-0.md @@ -0,0 +1,12 @@ +# Creating a Sidebar for Your Plugin + +This tutorial starts with you having an existing plugin setup and ready to add PHP and JavaScript code. Please, refer to [Getting started with JavaScript](/docs/how-to-guides/javascript/) tutorial for an introduction to WordPress plugins and how to use JavaScript to extend the block editor. + + In the next sections, you're going to create a custom sidebar for a plugin that contains a text control so the user can update a value that is stored in the `post_meta` table. + +1. [Get a sidebar up and running](/docs/how-to-guides/sidebar-tutorial/plugin-sidebar-1-up-and-running.md) +2. [Tweak the sidebar style and add controls](/docs/how-to-guides/sidebar-tutorial/plugin-sidebar-2-styles-and-controls.md) +3. [Register a new meta field](/docs/how-to-guides/sidebar-tutorial/plugin-sidebar-3-register-meta.md) +4. [Initialize the input control with the meta field value](/docs/how-to-guides/sidebar-tutorial/plugin-sidebar-4-initialize-input.md) +5. [Update the meta field value when input's content changes](/docs/how-to-guides/sidebar-tutorial/plugin-sidebar-5-update-meta.md) +6. [Finishing touches](/docs/how-to-guides/sidebar-tutorial/plugin-sidebar-6-finishing-touches.md) diff --git a/docs/designers-developers/developers/tutorials/sidebar-tutorial/plugin-sidebar-1-up-and-running.md b/docs/how-to-guides/sidebar-tutorial/plugin-sidebar-1-up-and-running.md similarity index 90% rename from docs/designers-developers/developers/tutorials/sidebar-tutorial/plugin-sidebar-1-up-and-running.md rename to docs/how-to-guides/sidebar-tutorial/plugin-sidebar-1-up-and-running.md index a241920029ce3d..0f7a9410b78596 100644 --- a/docs/designers-developers/developers/tutorials/sidebar-tutorial/plugin-sidebar-1-up-and-running.md +++ b/docs/how-to-guides/sidebar-tutorial/plugin-sidebar-1-up-and-running.md @@ -1,6 +1,6 @@ # Get a Sidebar up and Running -The first step in the journey is to tell the editor that there is a new plugin that will have its own sidebar. You can do so by using the [registerPlugin](/packages/plugins/README.md), [PluginSidebar](/packages/edit-post/README.md#pluginsidebar), and [createElement](/packages/element/README.md) utilities provided by WordPress, to be found in the `@wordpress/plugins`, `@wordpress/edit-post`, and `@wordpress/element` [packages](/docs/designers-developers/developers/packages.md), respectively. +The first step in the journey is to tell the editor that there is a new plugin that will have its own sidebar. You can do so by using the [registerPlugin](/packages/plugins/README.md), [PluginSidebar](/packages/edit-post/README.md#pluginsidebar), and [createElement](/packages/element/README.md) utilities provided by WordPress, to be found in the `@wordpress/plugins`, `@wordpress/edit-post`, and `@wordpress/element` [packages](/docs/reference-guides/packages.md), respectively. Add the following code to a JavaScript file called `plugin-sidebar.js` and save it within your plugin's directory: @@ -53,4 +53,4 @@ add_action( 'enqueue_block_editor_assets', 'sidebar_plugin_script_enqueue' ); After installing and activating this plugin, there is a new icon resembling a tack in the top-right of the editor. Upon clicking it, the plugin's sidebar will be opened: -![Sidebar Up and Running](https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/assets/sidebar-up-and-running.png) +![Sidebar Up and Running](https://raw.githubusercontent.com/WordPress/gutenberg/HEAD/docs/assets/sidebar-up-and-running.png) diff --git a/docs/designers-developers/developers/tutorials/sidebar-tutorial/plugin-sidebar-2-styles-and-controls.md b/docs/how-to-guides/sidebar-tutorial/plugin-sidebar-2-styles-and-controls.md similarity index 97% rename from docs/designers-developers/developers/tutorials/sidebar-tutorial/plugin-sidebar-2-styles-and-controls.md rename to docs/how-to-guides/sidebar-tutorial/plugin-sidebar-2-styles-and-controls.md index d919d11c657aed..841c9f1153446a 100644 --- a/docs/designers-developers/developers/tutorials/sidebar-tutorial/plugin-sidebar-2-styles-and-controls.md +++ b/docs/how-to-guides/sidebar-tutorial/plugin-sidebar-2-styles-and-controls.md @@ -92,6 +92,6 @@ add_action( 'enqueue_block_assets', 'sidebar_plugin_style_enqueue' ); Reload the editor and open the sidebar: -![Sidebar with style and controls](https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/assets/sidebar-style-and-controls.png) +![Sidebar with style and controls](https://raw.githubusercontent.com/WordPress/gutenberg/HEAD/docs/assets/sidebar-style-and-controls.png) With the input control and the styling the sidebar looks nicer. This code doesn't let users to store or retrieve data just yet, so the next steps will focus on how to connect it to the meta block field. diff --git a/docs/designers-developers/developers/tutorials/sidebar-tutorial/plugin-sidebar-3-register-meta.md b/docs/how-to-guides/sidebar-tutorial/plugin-sidebar-3-register-meta.md similarity index 90% rename from docs/designers-developers/developers/tutorials/sidebar-tutorial/plugin-sidebar-3-register-meta.md rename to docs/how-to-guides/sidebar-tutorial/plugin-sidebar-3-register-meta.md index afa859da1e35ca..fc1e15024a85a6 100644 --- a/docs/designers-developers/developers/tutorials/sidebar-tutorial/plugin-sidebar-3-register-meta.md +++ b/docs/how-to-guides/sidebar-tutorial/plugin-sidebar-3-register-meta.md @@ -12,7 +12,7 @@ register_post_meta( 'post', 'sidebar_plugin_meta_block_field', array( ) ); ``` -To make sure the field has been loaded, query the block editor [internal data structures](/docs/designers-developers/developers/data/), also known as _stores_. Open your browser's console, and execute this piece of code: +To make sure the field has been loaded, query the block editor [internal data structures](/docs/reference-guides/data/), also known as _stores_. Open your browser's console, and execute this piece of code: ```js wp.data.select( 'core/editor' ).getCurrentPost().meta; diff --git a/docs/designers-developers/developers/tutorials/sidebar-tutorial/plugin-sidebar-4-initialize-input.md b/docs/how-to-guides/sidebar-tutorial/plugin-sidebar-4-initialize-input.md similarity index 91% rename from docs/designers-developers/developers/tutorials/sidebar-tutorial/plugin-sidebar-4-initialize-input.md rename to docs/how-to-guides/sidebar-tutorial/plugin-sidebar-4-initialize-input.md index bc602e39b27983..94e7e52db98ccd 100644 --- a/docs/designers-developers/developers/tutorials/sidebar-tutorial/plugin-sidebar-4-initialize-input.md +++ b/docs/how-to-guides/sidebar-tutorial/plugin-sidebar-4-initialize-input.md @@ -105,7 +105,7 @@ This is how the code changes from the previous section: * The `MetaBlockField` function has now a `props` argument as input. It contains the data object returned by the `mapSelectToProps` function, which it uses to initialize its value property. * The component rendered within the `div` element was also updated, the plugin now uses `MetaBlockFieldWithData`. This will be updated every time the original data changes. -* [getEditedPostAttribute](/docs/designers-developers/developers/data/data-core-editor.md#geteditedpostattribute) is used to retrieve data instead of [getCurrentPost](/docs/designers-developers/developers/data/data-core-editor.md#getcurrentpost) because it returns the most recent values of the post, including user editions that haven't been yet saved. +* [getEditedPostAttribute](/docs/reference-guides/data/data-core-editor.md#geteditedpostattribute) is used to retrieve data instead of [getCurrentPost](/docs/reference-guides/data/data-core-editor.md#getcurrentpost) because it returns the most recent values of the post, including user editions that haven't been yet saved. Update the code and open the sidebar. The input's content is no longer `Initial value` but a void string. Users can't type values yet, but let's check that the component is updated if the value in the store changes. Open the browser's console, execute diff --git a/docs/designers-developers/developers/tutorials/sidebar-tutorial/plugin-sidebar-5-update-meta.md b/docs/how-to-guides/sidebar-tutorial/plugin-sidebar-5-update-meta.md similarity index 100% rename from docs/designers-developers/developers/tutorials/sidebar-tutorial/plugin-sidebar-5-update-meta.md rename to docs/how-to-guides/sidebar-tutorial/plugin-sidebar-5-update-meta.md diff --git a/docs/designers-developers/developers/tutorials/sidebar-tutorial/plugin-sidebar-6-finishing-touches.md b/docs/how-to-guides/sidebar-tutorial/plugin-sidebar-6-finishing-touches.md similarity index 100% rename from docs/designers-developers/developers/tutorials/sidebar-tutorial/plugin-sidebar-6-finishing-touches.md rename to docs/how-to-guides/sidebar-tutorial/plugin-sidebar-6-finishing-touches.md diff --git a/docs/designers-developers/developers/themes/README.md b/docs/how-to-guides/themes/README.md similarity index 100% rename from docs/designers-developers/developers/themes/README.md rename to docs/how-to-guides/themes/README.md diff --git a/docs/designers-developers/developers/themes/block-based-themes.md b/docs/how-to-guides/themes/block-based-themes.md similarity index 95% rename from docs/designers-developers/developers/themes/block-based-themes.md rename to docs/how-to-guides/themes/block-based-themes.md index 34d37f32c403d8..dc931cc203b11c 100644 --- a/docs/designers-developers/developers/themes/block-based-themes.md +++ b/docs/how-to-guides/themes/block-based-themes.md @@ -31,7 +31,7 @@ theme |__ ... ``` -The difference with existing WordPress themes is that the different templates in the template hierarchy, and template parts, are block templates instead of php files. In addition, this example includes an [`experimental-theme.json`](/docs/designers-developers/developers/themes/theme-json.md) file for some styles. +The difference with existing WordPress themes is that the different templates in the template hierarchy, and template parts, are block templates instead of php files. In addition, this example includes an [`experimental-theme.json`](/docs/how-to-guides/themes/theme-json.md) file for some styles. ## What is a block template? @@ -76,7 +76,7 @@ As of Gutenberg 8.5, there are two ways to create and edit templates within Gute ### Edit templates within The "Appearance" section of WP-Admin -You can navigate to the temporary "Templates" admin menu under "Appearance" `wp-admin/edit.php?post_type=wp_template` and use this as a playground to edit your templates. Add blocks here and switch to the code editor mode to grab the HTML of the template when you are done. Afterwards, you can paste that markup into a file within in your theme directory. +You can navigate to the temporary "Templates" admin menu under "Appearance" `wp-admin/edit.php?post_type=wp_template` and use this as a playground to edit your templates. Add blocks here and switch to the code editor mode to grab the HTML of the template when you are done. Afterwards, you can paste that markup into a file in your theme directory. Please note that the "Templates" admin menu under "Appearance" will _not_ list templates that are bundled with your theme. It only lists new templates created by the specific WordPress site you're working on. @@ -126,7 +126,7 @@ As we're still early in the process, the number of blocks specifically dedicated ## Styling -One of the most important aspects of themes (if not the most important) is the styling. While initially you'll be able to provide styles and enqueue them using the same hooks themes have always used, the [Global Styles](/docs/designers-developers/developers/themes/theme-json.md) effort will provide a scaffolding for adding many theme styles in the future. +One of the most important aspects of themes (if not the most important) is the styling. While initially you'll be able to provide styles and enqueue them using the same hooks themes have always used, the [Global Styles](/docs/how-to-guides/themes/theme-json.md) effort will provide a scaffolding for adding many theme styles in the future. ## Resources diff --git a/docs/how-to-guides/themes/theme-json.md b/docs/how-to-guides/themes/theme-json.md new file mode 100644 index 00000000000000..74831234b7f547 --- /dev/null +++ b/docs/how-to-guides/themes/theme-json.md @@ -0,0 +1,577 @@ +# Themes & Block Editor: experimental theme.json + +> **These features are still experimental**. “Experimental” means this is an early implementation subject to drastic and breaking changes. +> +> Documentation has been shared early to surface what’s being worked on and invite feedback from those experimenting with the APIs. Please, be welcomed to share yours in the weekly #core-editor chats as well as async via the Github issues and Pull Requests. + +This is documentation for the current direction and work in progress about how themes can hook into the various sub-systems that the Block Editor provides. + +- Rationale + - Settings can be controlled per block + - Some block styles are managed + - CSS Custom Properties: presets & custom +- Specification + - Settings + - Styles + - Other theme metadata +- FAQ + - The naming schema of CSS Custom Properties + - Why using -- as a separator? + - How settings under "custom" create new CSS Custom Properties + +## Rationale + +The Block Editor API has evolved at different velocities and there are some growing pains, specially in areas that affect themes. Examples of this are: the ability to [control the editor programmatically](https://make.wordpress.org/core/2020/01/23/controlling-the-block-editor/), or [a block style system](https://github.com/WordPress/gutenberg/issues/9534) that facilitates user, theme, and core style preferences. + +This describes the current efforts to consolidate the various APIs related to styles into a single point – a `experimental-theme.json` file that should be located inside the root of the theme directory. + +### Settings can be controlled per block + +The Block Editor already allows the control of specific settings such as alignment, drop cap, presets available, etc. All of these work at the block level. By using the `experimental-theme.json` we aim to allow themes to control these at a block level. + +Examples of what can be achieved are: + +- Use a particular preset for a block (e.g.: table) but the common one for the rest of blocks. +- Enable font size UI controls for all blocks that support it but the headings block. +- etc. + +### Some block styles are managed + +By using the `experimental-theme.json` file to set style properties in a structured way, the Block Editor can "manage" the CSS that comes from different origins (user, theme, and core CSS). For example, if a theme and a user set the font size for paragraphs, we only enqueue the style coming from the user and not the theme's. + +Some of the advantages are: + +- Reduce the amount of CSS enqueued. +- Prevent specificity wars. + +### CSS Custom Properties + +There are some areas of styling that would benefit from having shared values that can change across a site instantly. + +To address this need, we've started to experiment with CSS Custom Properties, aka CSS Variables, in some places: + +- **Presets**: [color palettes](https://developer.wordpress.org/block-editor/developers/themes/theme-support/#block-color-palettes), [font sizes](https://developer.wordpress.org/block-editor/developers/themes/theme-support/#block-font-sizes), or [gradients](https://developer.wordpress.org/block-editor/developers/themes/theme-support/#block-gradient-presets) declared by the theme are converted to CSS Custom Properties and enqueued both the front-end and the editors. + +{% codetabs %} +{% Input %} +```json +{ + "settings": { + "defaults": { + "color": { + "palette": [ + { + "name": "Black", + "slug": "black", + "color": "#000000" + }, + { + "name": "White", + "slug": "white", + "color": "#ffffff" + } + ], + }, + }, + }, +} +``` +{% Output %} +```css +:root { + --wp--preset--color--black: #000000; + --wp--preset--color--white: #ffffff; +} +``` +{% end %} + +- **Custom properties**: there's also a mechanism to create your own CSS Custom Properties. + +{% codetabs %} +{% Input %} +```json +{ + "settings": { + "defaults": { + "custom": { + "line-height": { + "body": 1.7, + "heading": 1.3 + }, + }, + }, + }, +} +``` +{% Output %} +```css +:root { + --wp--custom--line-height--body: 1.7; + --wp--custom--line-height--heading: 1.3; +} +``` +{% end %} + +## Specification + +This specification is the same for the three different origins that use this format: core, themes, and users. Themes can override core's defaults by creating a file called `experimental-theme.json`. Users, via the site editor, will also be also to override theme's or core's preferences via an user interface that is being worked on. + +The `experimental-theme.json` file declares how a theme wants the editor configured (`settings`) as well as the style properties it sets (`styles`). + +``` +{ + "settings": { ... }, + "styles": { ... } +} +``` + +Both settings and styles can contain subsections for any registered block. As a general rule, the names of these subsections will be the block names ― we call them "block selectors". For example, the paragraph block ―whose name is `core/paragraph`― can be addressed in the settings using the key (or "block selector") `core/paragraph`: + +``` +{ + "settings": { + "core/paragraph": { ... } + } +} +``` + +There are a few cases in whiche a single block can represent different HTML markup. The heading block is one of these, as it represents h1 to h6 HTML elements. In these cases, the block will have as many block selectors as different markup variations ― `core/heading/h1`, `core/heading/h2`, etc, so they can be addressed separately: + +``` +{ + "styles": { + "core/heading/h1": { ... }, + // ... + "core/heading/h6": { ... }, + } +} +``` + +Additionally, there are two other block selectors: `root` and `defaults`. The `root` block selector represents the root of the site. The `defaults` block selector represents the defaults to be used by blocks if they don't declare anything. + +### Settings + +The settings section has the following structure and default values: + +``` +{ + "settings": { + "some/block": { + "border": { + "customRadius": false /* true to opt-in */ + }, + "color": { + "custom": true, /* false to opt-out, as in add_theme_support('disable-custom-colors') */ + "customGradient": true, /* false to opt-out, as in add_theme_support('disable-custom-gradients') */ + "gradients": [ ... ], /* gradient presets, as in add_theme_support('editor-gradient-presets', ... ) */ + "link": false, /* true to opt-in, as in add_theme_support('experimental-link-color') */ + "palette": [ ... ], /* color presets, as in add_theme_support('editor-color-palette', ... ) */ + }, + "custom": { ... }, + "spacing": { + "customPadding": false, /* true to opt-in, as in add_theme_support('custom-spacing') */ + "units": [ "px", "em", "rem", "vh", "vw" ], /* filter values, as in add_theme_support('custom-units', ... ) */ + }, + "typography": { + "customFontSize": true, /* false to opt-out, as in add_theme_support( 'disable-custom-font-sizes' ) */ + "customFontWeight": true, /* false to opt-out */ + "customFontStyle": true, /* false to opt-out */ + "customLineHeight": false, /* true to opt-in, as in add_theme_support( 'custom-line-height' ) */ + "dropCap": true, /* false to opt-out */ + "fontFamilies": [ ... ], /* font family presets */ + "fontSizes": [ ... ], /* font size presets, as in add_theme_support('editor-font-sizes', ... ) */ + } + } + } +} +``` + +Each block can configure any of these settings separately, providing a more fine-grained control over what exists via `add_theme_support`. + +The block settings declared under the `defaults` block selector affect to all blocks, unless a particular block overwrites it. It's a way to provide inheritance and quickly configure all blocks at once. To retain backward compatibility, the existing `add_theme_support` declarations that configure the block editor are retrofit in the proper categories for the `defaults` section. If a theme uses `add_theme_support('disable-custom-colors')`, it'll be the same as set `settings.defaults.color.custom` to `false`. If the `experimental-theme.json` contains any settings, these will take precedence over the values declared via `add_theme_support`. + +Let's say a theme author wants to enable custom colors only for the paragraph block. This is how it can be done: + +``` +{ + "settings": { + "defaults": { + "color": { + "custom": false // Disable it for all blocks. + } + }, + "core/paragraph": { + "color": { + "custom": true // Paragraph overrides the setting. + } + } + } +} +``` + +Note, however, that not all settings are relevant for all blocks. The settings section provides an opt-in/opt-out mechanism for themes, but it's the block's responsibility to add support for the features that are relevant to it. For example, if a block doesn't implement the `dropCap` feature, a theme can't enable it for such a block through `experimental-theme.json`. + +#### Presets + +Presets are part of the settings section. Each preset value will generate a CSS Custom Property that will be added to the new stylesheet, which follow this naming schema: `--wp--preset--{preset-category}--{preset-slug}`. + +For example: + +{% codetabs %} +{% Input %} +```json +{ + "settings": { + "defaults": { + "color": { + "palette": [ + { + "slug": "strong-magenta", + "color": "#a156b4" + }, + { + "slug": "very-dark-grey", + "color": "rgb(131, 12, 8)" + } + ], + "gradients": [ + { + "slug": "blush-bordeaux", + "gradient": "linear-gradient(135deg,rgb(254,205,165) 0%,rgb(254,45,45) 50%,rgb(107,0,62) 100%)" + }, + { + "slug": "blush-light-purple", + "gradient": "linear-gradient(135deg,rgb(255,206,236) 0%,rgb(152,150,240) 100%)" + }, + ] + }, + "typography": { + "fontSizes": [ + { + "slug": "normal", + "size": 16 + }, + { + "slug": "big", + "size": 32 + } + ] + } + } + } +} +``` +{% Output %} +```css +:root { + --wp--preset--color--strong-magenta: #a156b4; + --wp--preset--color--very-dark-gray: #444; + --wp--preset--font-size--big: 32; + --wp--preset--font-size--normal: 16; + --wp--preset--gradient--blush-bordeaux: linear-gradient(135deg,rgb(254,205,165) 0%,rgb(254,45,45) 50%,rgb(107,0,62) 100%); + --wp--preset--gradient--blush-light-purple: linear-gradient(135deg,rgb(255,206,236) 0%,rgb(152,150,240) 100%); +} +``` +{% end %} + +To maintain backward compatibility, the presets declared via `add_theme_support` will also generate the CSS Custom Properties. If the `experimental-theme.json` contains any presets, these will take precedence over the ones declared via `add_theme_support`. + +#### Free-form CSS Custom Properties + +In addition to create CSS Custom Properties for the presets, the `experimental-theme.json` also allows for themes to create their own, so they don't have to be enqueued separately. Any values declared within the `settings..custom` section will be transformed to CSS Custom Properties following this naming schema: `--wp--custom--`. + +For example: + +{% codetabs %} +{% Input %} +```json +{ + "settings": { + "defaults": { + "custom": { + "base-font": 16, + "line-height": { + "small": 1.2, + "medium": 1.4, + "large": 1.8 + } + } + } + } +} +``` +{% Output %} +```css +:root { + --wp--custom--base-font: 16; + --wp--custom--line-height--small: 1.2; + --wp--custom--line-height--medium: 1.4; + --wp--custom--line-height--large: 1.8; +} +``` +{% end %} + +Note that, the name of the variable is created by adding `--` in between each nesting level. + +### Styles + +Each block declares which style properties it exposes via the [block supports mechanism](../block-api/block-supports.md). The support declarations are used to automatically generate the UI controls for the block in the editor, as well as being available through the `experimental-theme.json` file for themes to target. + +```json +{ + "styles": { + "some/block/selector": { + "border": { + "radius": "value" + }, + "color": { + "background": "value", + "gradient": "value", + "link": "value", + "text": "value" + }, + "spacing": { + "padding": { + "top": "value", + "right": "value", + "bottom": "value", + "left": "value", + }, + }, + "typography": { + "fontFamily": "value", + "fontSize": "value", + "fontStyle": "value", + "fontWeight": "value", + "lineHeight": "value", + "textDecoration": "value", + "textTransform": "value" + } + } + } +} +``` + +For example: + +{% codetabs %} +{% Input %} +```json +{ + "styles": { + "root": { + "color": { + "text": "var(--wp--preset--color--primary)" + }, + }, + "core/heading/h1": { + "color": { + "text": "var(--wp--preset--color--primary)" + }, + "typography": { + "fontSize": "calc(1px * var(--wp--preset--font-size--huge))" + } + }, + "core/heading/h4": { + "color": { + "text": "var(--wp--preset--color--secondary)" + }, + "typography": { + "fontSize": "var(--wp--preset--font-size--normal)" + } + } + } +} +``` +{% Output %} +```css +:root { + color: var(--wp--preset--color--primary); +} +h1 { + color: var(--wp--preset--color--primary); + font-size: calc(1px * var(--wp--preset--font-size--huge)); +} +h4 { + color: var(--wp--preset--color--secondary); + font-size: calc(1px * var(--wp--preset--font-size--normal)); +} +``` +{% end %} + +The `defaults` block selector can't be part of the `styles` section and will be ignored if it's present. The `root` block selector will generate a style rule with the `:root` CSS selector. + +#### Border Properties + +| Block | Color | Radius | Style | Width | +| --- | --- | --- | --- | --- | +| Group | Yes | Yes | Yes | Yes | +| Image | Yes | - | - | - | + +#### Color Properties + +These are the current color properties supported by blocks: + +| Block | Background | Gradient | Link | Text | +| --- | --- | --- | --- | --- | +| Global | Yes | Yes | Yes | Yes | +| Columns | Yes | Yes | Yes | Yes | +| Group | Yes | Yes | Yes | Yes | +| Heading [1] | Yes | - | Yes | Yes | +| List | Yes | Yes | - | Yes | +| Media & text | Yes | Yes | Yes | Yes | +| Navigation | Yes | - | - | Yes | +| Paragraph | Yes | - | Yes | Yes | +| Post Author | Yes | Yes | Yes | Yes | +| Post Comments | Yes | Yes | Yes | Yes | +| Post Comments Count | Yes | Yes | - | Yes | +| Post Comments Form | Yes | Yes | Yes | Yes | +| Post Date | Yes | Yes | - | Yes | +| Post Excerpt | Yes | Yes | Yes | Yes | +| Post Hierarchical Terms | Yes | Yes | Yes | Yes | +| Post Tags | Yes | Yes | Yes | Yes | +| Post Title | Yes | Yes | - | Yes | +| Site Tagline | Yes | Yes | - | Yes | +| Site Title | Yes | Yes | - | Yes | +| Template Part | Yes | Yes | Yes | Yes | + +[1] The heading block represents 6 distinct HTML elements: H1-H6. It comes with selectors to target each individual element (ex: core/heading/h1 for H1, etc). + +#### Spacing Properties + +| Block | Padding | +| --- | --- | +| Cover | Yes | +| Group | Yes | + +#### Typography Properties + +These are the current typography properties supported by blocks: + +| Block | Font Family | Font Size | Font Style | Font Weight | Line Height | Text Decoration | Text Transform | +| --- | --- | --- | --- | --- | --- | --- | --- | +| Global | Yes | Yes | Yes | Yes | Yes | Yes | Yes | +| Code | - | Yes | - | - | - | - | - | +| Heading [1] | - | Yes | - | - | Yes | - | - | +| List | - | Yes | - | - | - | - | - | +| Navigation | Yes | Yes | Yes | Yes | - | Yes | Yes | +| Paragraph | - | Yes | - | - | Yes | - | - | +| Post Author | - | Yes | - | - | Yes | - | - | +| Post Comments | - | Yes | - | - | Yes | - | - | +| Post Comments Count | - | Yes | - | - | Yes | - | - | +| Post Comments Form | - | Yes | - | - | Yes | - | - | +| Post Date | - | Yes | - | - | Yes | - | - | +| Post Excerpt | - | Yes | - | - | Yes | - | - | +| Post Hierarchical Terms | - | Yes | - | - | Yes | - | - | +| Post Tags | - | Yes | - | - | Yes | - | - | +| Post Title | Yes | Yes | - | - | Yes | - | - | +| Preformatted | - | Yes | - | - | - | - | - | +| Site Tagline | Yes | Yes | - | - | Yes | - | - | +| Site Title | Yes | Yes | - | - | Yes | - | Yes | +| Verse | Yes | Yes | - | - | - | - | - | + +[1] The heading block represents 6 distinct HTML elements: H1-H6. It comes with selectors to target each individual element (ex: core/heading/h1 for H1, etc). + + +### Other theme metadata + +There's a growing need to add more theme metadata to the theme.json. This section lists those other fields: + +**customTemplates**: within this field themes can list the custom templates present in the `block-templates` folder, the keys should match the custom template name. For example, for a custom template named `my-custom-template.html`, the `theme.json` can declare what post types can use it and what's the title to show the user: + +```json +{ + "customTemplates": { + "my-custom-template": { + "title": "The template title", /* Mandatory */ + "postTypes": [ "page", "post", "my-cpt" ] /* Optional, will only apply to "page" by default. */ + } + } +} +``` + +## Frequently Asked Questions + +### The naming schema of CSS Custom Properties + +One thing you may have noticed is the naming schema used for the CSS Custom Properties the system creates, including the use of double hyphen, `--`, to separate the different "concepts". Take the following examples. + +**Presets** such as `--wp--preset--color--black` can be divided into the following chunks: + +- `--wp`: prefix to namespace the CSS variable. +- `preset `: indicates is a CSS variable that belongs to the presets. +- `color`: indicates which preset category the variable belongs to. It can be `color`, `font-size`, `gradients`. +- `black`: the `slug` of the particular preset value. + +**Custom** properties such as `--wp--custom--line-height--body`, which can be divided into the following chunks: + +- `--wp`: prefix to namespace the CSS variable. +- `custom`: indicates is a "free-form" CSS variable created by the theme. +- `line-height--body`: the result of converting the "custom" object keys into a string. + +The `--` as a separator has two functions: + +- Readibility, for human understanding. It can be thought as similar to the BEM naming schema, it separates "categories". +- Parseability, for machine understanding. Using a defined structure allows machines to understand the meaning of the property `--wp--preset--color--black`: it's a value bounded to the color preset whose slug is "black", which then gives us room to do more things with them. + +### Why using `--` as a separator? + +We could have used any other separator, such as a single `-`. + +However, that'd have been problematic, as it'd have been impossible to tell how `--wp-custom-line-height-template-header` should be converted back into an object, unless we force theme authors not to use `-` in their variable names. + +By reserving `--` as a category separator and let theme authors use `-` for word-boundaries, the naming is clearer: `--wp--custom--line-height--template-header`. + +### How settings under "custom" create new CSS Custom Properties + +The algorithm to create CSS Variables out of the settings under the "custom" key works this way: + +This is for clarity, but also because we want a mechanism to parse back a variable name such `--wp--custom--line-height--body` to its object form in theme.json. We use the same separation for presets. + +For example: + +{% codetabs %} +{% Input %} +```json +{ + "settings": { + "defaults": { + "custom": { + "lineHeight": { + "body": 1.7 + }, + "font-primary": "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen-Sans, Ubuntu, Cantarell, 'Helvetica Neue', sans-serif" + }, + }, + }, +} +``` +{% Output %} +```css +:root { + --wp--custom--line-height--body: 1.7; + --wp--custom--font-primary: "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen-Sans, Ubuntu, Cantarell, 'Helvetica Neue', sans-serif", +} +``` +{% end %} + +A few notes about this process: + +- `camelCased` keys are transformed into its `kebab-case` form, as to follow the CSS property naming schema. Example: `lineHeight` is transformed into `line-height`. +- Keys at different depth levels are separated by `--`. That's why `line-height` and `body` are separated by `--`. +- You shouldn't use `--` in the names of the keys within the `custom` object. Example, **don't do** this: + + +```json +{ + "settings": { + "defaults": { + "custom": { + "line--height": { + "body": 1.7 + }, + }, + }, + }, +} +``` diff --git a/docs/designers-developers/developers/themes/theme-support.md b/docs/how-to-guides/themes/theme-support.md similarity index 94% rename from docs/designers-developers/developers/themes/theme-support.md rename to docs/how-to-guides/themes/theme-support.md index 5f022bca7094db..1b434af064b1d9 100644 --- a/docs/designers-developers/developers/themes/theme-support.md +++ b/docs/how-to-guides/themes/theme-support.md @@ -8,7 +8,6 @@ There are a few new concepts to consider when building themes: - **Editor Text Size Palette** - A default set of sizes is provided, but themes can register their own and optionally lock users into picking from preselected sizes. - **Responsive Embeds** - Themes must opt-in to responsive embeds. - **Frontend & Editor Styles** - To get the most out of blocks, theme authors will want to make sure Core styles look good and opt-in, or write their own styles to best fit their theme. -- **Dark Mode** - If a Theme is a Dark Theme with a dark background containing light text, the theme author can opt-in to the Dark Mode. - **Block Tools** - Themes can opt-in to several block tools like line height, custom units. - **Core Block Patterns** - Themes can opt-out of the default block patterns. @@ -316,17 +315,6 @@ add_theme_support( 'editor-styles' ); You shouldn't need to change your editor styles too much; most themes can add the snippet above and get similar results in the classic editor and inside the block editor. -### Dark backgrounds - -If your editor style relies on a dark background, you can add the following to adjust the color of the UI to work on dark backgrounds: - -```php -add_theme_support( 'editor-styles' ); -add_theme_support( 'dark-editor-style' ); -``` - -Note you don't need to add `add_theme_support( 'editor-styles' );` twice, but that rule does need to be present for the `dark-editor-style` rule to work. - ### Enqueuing the editor style Use the `add_editor_style` function to enqueue and load CSS on the editor screen. For the classic editor, this was the only function needed to add style to the editor. For the new block editor, you first need to `add_theme_support( 'editor-styles');` mentioned above. @@ -372,7 +360,7 @@ To change the main column width of the editor, add the following CSS to `style-e You can use those editor widths to match those in your theme. You can use any CSS width unit, including `%` or `px`. -Further reading: [Applying Styles with Stylesheets](/docs/designers-developers/developers/tutorials/block-tutorial/applying-styles-with-stylesheets.md). +Further reading: [Applying Styles with Stylesheets](/docs/how-to-guides/block-tutorial/applying-styles-with-stylesheets.md). ## Responsive embedded content @@ -390,7 +378,7 @@ add_theme_support( 'responsive-embeds' ); ## Spacing control -Using the Gutenberg plugin (version 8.3 or later), some blocks can provide padding controls in the editor for users. This is off by default, and requires the theme to opt in by declaring support: +Some blocks can have padding controls. This is off by default, and requires the theme to opt in by declaring support: ```php add_theme_support('custom-spacing'); diff --git a/docs/manifest.json b/docs/manifest.json index 8c0881895f1428..c72f2673adf4b1 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -1,777 +1,621 @@ [ { - "title": "Project Overview", + "title": "Getting started", "slug": "handbook", - "markdown_source": "../docs/readme.md", + "markdown_source": "../docs/README.md", "parent": null }, { - "title": "Glossary", - "slug": "glossary", - "markdown_source": "../docs/designers-developers/glossary.md", + "title": "Tutorials", + "slug": "tutorials", + "markdown_source": "../docs/getting-started/tutorials/README.md", "parent": "handbook" }, { - "title": "Frequently Asked Questions", - "slug": "faq", - "markdown_source": "../docs/designers-developers/faq.md", - "parent": "handbook" + "title": "Development Environment", + "slug": "devenv", + "markdown_source": "../docs/getting-started/tutorials/devenv/README.md", + "parent": "tutorials" }, { - "title": "Versions in WordPress", - "slug": "versions-in-wordpress", - "markdown_source": "../docs/contributors/versions-in-wordpress.md", - "parent": "handbook" + "title": "How to setup local WordPress environment on Ubuntu", + "slug": "docker-ubuntu", + "markdown_source": "../docs/getting-started/tutorials/devenv/docker-ubuntu.md", + "parent": "devenv" }, { - "title": "History", - "slug": "history", - "markdown_source": "../docs/contributors/history.md", - "parent": "handbook" + "title": "Create a Block Tutorial", + "slug": "create-block", + "markdown_source": "../docs/getting-started/tutorials/create-block/README.md", + "parent": "tutorials" }, { - "title": "Outreach", - "slug": "outreach", - "markdown_source": "../docs/contributors/outreach.md", - "parent": "handbook" + "title": "WordPress Plugin", + "slug": "wp-plugin", + "markdown_source": "../docs/getting-started/tutorials/create-block/wp-plugin.md", + "parent": "create-block" }, { - "title": "Architecture", - "slug": "architecture", - "markdown_source": "../docs/architecture/readme.md", - "parent": null + "title": "Anatomy of a Block", + "slug": "block-anatomy", + "markdown_source": "../docs/getting-started/tutorials/create-block/block-anatomy.md", + "parent": "create-block" }, { - "title": "Key Concepts", - "slug": "key-concepts", - "markdown_source": "../docs/architecture/key-concepts.md", - "parent": "architecture" + "title": "Block Attributes", + "slug": "attributes", + "markdown_source": "../docs/getting-started/tutorials/create-block/attributes.md", + "parent": "create-block" }, { - "title": "Data Flow and Data Format", - "slug": "data-flow", - "markdown_source": "../docs/architecture/data-flow.md", - "parent": "architecture" + "title": "Code Implementation", + "slug": "block-code", + "markdown_source": "../docs/getting-started/tutorials/create-block/block-code.md", + "parent": "create-block" }, { - "title": "Folder Structure", - "slug": "folder-structure", - "markdown_source": "../docs/architecture/folder-structure.md", - "parent": "architecture" + "title": "Authoring Experience", + "slug": "author-experience", + "markdown_source": "../docs/getting-started/tutorials/create-block/author-experience.md", + "parent": "create-block" }, { - "title": "Modularity", - "slug": "modularity", - "markdown_source": "../docs/architecture/modularity.md", - "parent": "architecture" + "title": "Finishing Touches", + "slug": "finishing", + "markdown_source": "../docs/getting-started/tutorials/create-block/finishing.md", + "parent": "create-block" }, { - "title": "Performance", - "slug": "performance", - "markdown_source": "../docs/architecture/performance.md", - "parent": "architecture" + "title": "Share your Block with the World", + "slug": "submitting-to-block-directory", + "markdown_source": "../docs/getting-started/tutorials/create-block/submitting-to-block-directory.md", + "parent": "create-block" }, { - "title": "Automated Testing", - "slug": "automated-testing", - "markdown_source": "../docs/architecture/automated-testing.md", - "parent": "architecture" + "title": "Glossary", + "slug": "glossary", + "markdown_source": "../docs/getting-started/glossary.md", + "parent": "handbook" }, { - "title": "FseTemplates", - "slug": "fse-templates", - "markdown_source": "../docs/architecture/fse-templates.md", - "parent": "architecture" + "title": "Frequently Asked Questions", + "slug": "faq", + "markdown_source": "../docs/getting-started/faq.md", + "parent": "handbook" }, { - "title": "Developer Documentation", - "slug": "developers", - "markdown_source": "../docs/designers-developers/developers/README.md", - "parent": null + "title": "History", + "slug": "history", + "markdown_source": "../docs/getting-started/history.md", + "parent": "handbook" }, { - "title": "Block API Reference", - "slug": "block-api", - "markdown_source": "../docs/designers-developers/developers/block-api/README.md", - "parent": "developers" + "title": "Outreach", + "slug": "outreach", + "markdown_source": "../docs/getting-started/outreach.md", + "parent": "handbook" }, { - "title": "Block Registration", - "slug": "block-registration", - "markdown_source": "../docs/designers-developers/developers/block-api/block-registration.md", - "parent": "block-api" + "title": "How-to Guides", + "slug": "how-to-guides", + "markdown_source": "../docs/how-to-guides/README.md", + "parent": null }, { - "title": "Edit and Save", - "slug": "block-edit-save", - "markdown_source": "../docs/designers-developers/developers/block-api/block-edit-save.md", - "parent": "block-api" + "title": "Getting Started with JavaScript", + "slug": "javascript", + "markdown_source": "../docs/how-to-guides/javascript/README.md", + "parent": "how-to-guides" }, { - "title": "Attributes", - "slug": "block-attributes", - "markdown_source": "../docs/designers-developers/developers/block-api/block-attributes.md", - "parent": "block-api" + "title": "Plugins Background", + "slug": "plugins-background", + "markdown_source": "../docs/how-to-guides/javascript/plugins-background.md", + "parent": "javascript" }, { - "title": "Block Context", - "slug": "block-context", - "markdown_source": "../docs/designers-developers/developers/block-api/block-context.md", - "parent": "block-api" + "title": "Loading JavaScript", + "slug": "loading-javascript", + "markdown_source": "../docs/how-to-guides/javascript/loading-javascript.md", + "parent": "javascript" }, { - "title": "Deprecated Blocks", - "slug": "block-deprecation", - "markdown_source": "../docs/designers-developers/developers/block-api/block-deprecation.md", - "parent": "block-api" + "title": "Extending the Block Editor", + "slug": "extending-the-block-editor", + "markdown_source": "../docs/how-to-guides/javascript/extending-the-block-editor.md", + "parent": "javascript" }, { - "title": "Block Supports", - "slug": "block-supports", - "markdown_source": "../docs/designers-developers/developers/block-api/block-supports.md", - "parent": "block-api" + "title": "Troubleshooting", + "slug": "troubleshooting", + "markdown_source": "../docs/how-to-guides/javascript/troubleshooting.md", + "parent": "javascript" }, { - "title": "Block Transforms", - "slug": "block-transforms", - "markdown_source": "../docs/designers-developers/developers/block-api/block-transforms.md", - "parent": "block-api" + "title": "JavaScript Versions and Build Step", + "slug": "versions-and-building", + "markdown_source": "../docs/how-to-guides/javascript/versions-and-building.md", + "parent": "javascript" }, { - "title": "Templates", - "slug": "block-templates", - "markdown_source": "../docs/designers-developers/developers/block-api/block-templates.md", - "parent": "block-api" + "title": "Scope Your Code", + "slug": "scope-your-code", + "markdown_source": "../docs/how-to-guides/javascript/scope-your-code.md", + "parent": "javascript" }, { - "title": "Block Patterns", - "slug": "block-patterns", - "markdown_source": "../docs/designers-developers/developers/block-api/block-patterns.md", - "parent": "block-api" + "title": "JavaScript Build Setup", + "slug": "js-build-setup", + "markdown_source": "../docs/how-to-guides/javascript/js-build-setup.md", + "parent": "javascript" }, { - "title": "Annotations", - "slug": "block-annotations", - "markdown_source": "../docs/designers-developers/developers/block-api/block-annotations.md", - "parent": "block-api" + "title": "ESNext Syntax", + "slug": "esnext-js", + "markdown_source": "../docs/how-to-guides/javascript/esnext-js.md", + "parent": "javascript" }, { - "title": "Block API Versions", - "slug": "versions", - "markdown_source": "../docs/designers-developers/developers/block-api/versions.md", - "parent": "block-api" + "title": "Meta Boxes", + "slug": "metabox", + "markdown_source": "../docs/how-to-guides/metabox/README.md", + "parent": "how-to-guides" }, { - "title": "Filter Reference", - "slug": "filters", - "markdown_source": "../docs/designers-developers/developers/filters/README.md", - "parent": "developers" + "title": "Store Post Meta with a Block", + "slug": "meta-block-1-intro", + "markdown_source": "../docs/how-to-guides/metabox/meta-block-1-intro.md", + "parent": "metabox" }, { - "title": "Block Filters", - "slug": "block-filters", - "markdown_source": "../docs/designers-developers/developers/filters/block-filters.md", - "parent": "filters" + "title": "Register Meta Field", + "slug": "meta-block-2-register-meta", + "markdown_source": "../docs/how-to-guides/metabox/meta-block-2-register-meta.md", + "parent": "metabox" }, { - "title": "Editor Filters", - "slug": "editor-filters", - "markdown_source": "../docs/designers-developers/developers/filters/editor-filters.md", - "parent": "filters" + "title": "Create Meta Block", + "slug": "meta-block-3-add", + "markdown_source": "../docs/how-to-guides/metabox/meta-block-3-add.md", + "parent": "metabox" }, { - "title": "Parser Filters", - "slug": "parser-filters", - "markdown_source": "../docs/designers-developers/developers/filters/parser-filters.md", - "parent": "filters" + "title": "Use Post Meta Data", + "slug": "meta-block-4-use-data", + "markdown_source": "../docs/how-to-guides/metabox/meta-block-4-use-data.md", + "parent": "metabox" }, { - "title": "Autocomplete", - "slug": "autocomplete-filters", - "markdown_source": "../docs/designers-developers/developers/filters/autocomplete-filters.md", - "parent": "filters" + "title": "Finishing Touches", + "slug": "meta-block-5-finishing", + "markdown_source": "../docs/how-to-guides/metabox/meta-block-5-finishing.md", + "parent": "metabox" }, { - "title": "SlotFills Reference", - "slug": "slotfills", - "markdown_source": "../docs/designers-developers/developers/slotfills/README.md", - "parent": "developers" + "title": "Displaying Notices from Your Plugin or Theme", + "slug": "notices", + "markdown_source": "../docs/how-to-guides/notices/README.md", + "parent": "how-to-guides" }, { - "title": "MainDashboardButton", - "slug": "main-dashboard-button", - "markdown_source": "../docs/designers-developers/developers/slotfills/main-dashboard-button.md", - "parent": "slotfills" + "title": "Creating a Sidebar for Your Plugin", + "slug": "plugin-sidebar-0", + "markdown_source": "../docs/how-to-guides/sidebar-tutorial/plugin-sidebar-0.md", + "parent": "how-to-guides" }, { - "title": "PluginBlockSettingsMenuItem", - "slug": "plugin-block-settings-menu-item", - "markdown_source": "../docs/designers-developers/developers/slotfills/plugin-block-settings-menu-item.md", - "parent": "slotfills" + "title": "Get a Sidebar up and Running", + "slug": "plugin-sidebar-1-up-and-running", + "markdown_source": "../docs/how-to-guides/sidebar-tutorial/plugin-sidebar-1-up-and-running.md", + "parent": "plugin-sidebar-0" }, { - "title": "PluginDocumentSettingPanel", - "slug": "plugin-document-setting-panel", - "markdown_source": "../docs/designers-developers/developers/slotfills/plugin-document-setting-panel.md", - "parent": "slotfills" + "title": "Tweak the sidebar style and add controls", + "slug": "plugin-sidebar-2-styles-and-controls", + "markdown_source": "../docs/how-to-guides/sidebar-tutorial/plugin-sidebar-2-styles-and-controls.md", + "parent": "plugin-sidebar-0" }, { - "title": "PluginMoreMenuItem", - "slug": "plugin-more-menu-item", - "markdown_source": "../docs/designers-developers/developers/slotfills/plugin-more-menu-item.md", - "parent": "slotfills" + "title": "Register the Meta Field", + "slug": "plugin-sidebar-3-register-meta", + "markdown_source": "../docs/how-to-guides/sidebar-tutorial/plugin-sidebar-3-register-meta.md", + "parent": "plugin-sidebar-0" }, { - "title": "PluginPostPublishPanel", - "slug": "plugin-post-publish-panel", - "markdown_source": "../docs/designers-developers/developers/slotfills/plugin-post-publish-panel.md", - "parent": "slotfills" + "title": "Initialize the Input Control", + "slug": "plugin-sidebar-4-initialize-input", + "markdown_source": "../docs/how-to-guides/sidebar-tutorial/plugin-sidebar-4-initialize-input.md", + "parent": "plugin-sidebar-0" }, { - "title": "PluginPostStatusInfo", - "slug": "plugin-post-status-info", - "markdown_source": "../docs/designers-developers/developers/slotfills/plugin-post-status-info.md", - "parent": "slotfills" + "title": "Update the Meta Field When the Input's Content Changes", + "slug": "plugin-sidebar-5-update-meta", + "markdown_source": "../docs/how-to-guides/sidebar-tutorial/plugin-sidebar-5-update-meta.md", + "parent": "plugin-sidebar-0" }, { - "title": "PluginPrePublishPanel", - "slug": "plugin-pre-publish-panel", - "markdown_source": "../docs/designers-developers/developers/slotfills/plugin-pre-publish-panel.md", - "parent": "slotfills" + "title": "Finishing Touches", + "slug": "plugin-sidebar-6-finishing-touches", + "markdown_source": "../docs/how-to-guides/sidebar-tutorial/plugin-sidebar-6-finishing-touches.md", + "parent": "plugin-sidebar-0" }, { - "title": "PluginSidebar", - "slug": "plugin-sidebar", - "markdown_source": "../docs/designers-developers/developers/slotfills/plugin-sidebar.md", - "parent": "slotfills" + "title": "Blocks", + "slug": "block-tutorial", + "markdown_source": "../docs/how-to-guides/block-tutorial/README.md", + "parent": "how-to-guides" }, { - "title": "PluginSidebarMoreMenuItem", - "slug": "plugin-sidebar-more-menu-item", - "markdown_source": "../docs/designers-developers/developers/slotfills/plugin-sidebar-more-menu-item.md", - "parent": "slotfills" + "title": "Writing Your First Block Type", + "slug": "writing-your-first-block-type", + "markdown_source": "../docs/how-to-guides/block-tutorial/writing-your-first-block-type.md", + "parent": "block-tutorial" }, { - "title": "RichText Reference", - "slug": "richtext", - "markdown_source": "../docs/designers-developers/developers/richtext.md", - "parent": "developers" + "title": "Applying Styles From a Stylesheet", + "slug": "applying-styles-with-stylesheets", + "markdown_source": "../docs/how-to-guides/block-tutorial/applying-styles-with-stylesheets.md", + "parent": "block-tutorial" }, { - "title": "Internationalization", - "slug": "internationalization", - "markdown_source": "../docs/designers-developers/developers/internationalization.md", - "parent": "developers" + "title": "Introducing Attributes and Editable Fields", + "slug": "introducing-attributes-and-editable-fields", + "markdown_source": "../docs/how-to-guides/block-tutorial/introducing-attributes-and-editable-fields.md", + "parent": "block-tutorial" }, { - "title": "Accessibility", - "slug": "accessibility", - "markdown_source": "../docs/designers-developers/developers/accessibility.md", - "parent": "developers" + "title": "Block Controls: Block Toolbar and Settings Sidebar", + "slug": "block-controls-toolbar-and-sidebar", + "markdown_source": "../docs/how-to-guides/block-tutorial/block-controls-toolbar-and-sidebar.md", + "parent": "block-tutorial" }, { - "title": "Feature Flags", - "slug": "feature-flags", - "markdown_source": "../docs/designers-developers/developers/feature-flags.md", - "parent": "developers" + "title": "Creating dynamic blocks", + "slug": "creating-dynamic-blocks", + "markdown_source": "../docs/how-to-guides/block-tutorial/creating-dynamic-blocks.md", + "parent": "block-tutorial" }, { - "title": "Theming for the Block Editor", - "slug": "themes", - "markdown_source": "../docs/designers-developers/developers/themes/README.md", - "parent": "developers" + "title": "Generate Blocks with WP-CLI", + "slug": "generate-blocks-with-wp-cli", + "markdown_source": "../docs/how-to-guides/block-tutorial/generate-blocks-with-wp-cli.md", + "parent": "block-tutorial" }, { - "title": "Theme Support", - "slug": "theme-support", - "markdown_source": "../docs/designers-developers/developers/themes/theme-support.md", - "parent": "themes" + "title": "Nested Blocks: Using InnerBlocks", + "slug": "nested-blocks-inner-blocks", + "markdown_source": "../docs/how-to-guides/block-tutorial/nested-blocks-inner-blocks.md", + "parent": "block-tutorial" + }, + { + "title": "Feature Flags", + "slug": "feature-flags", + "markdown_source": "../docs/how-to-guides/feature-flags.md", + "parent": "how-to-guides" + }, + { + "title": "Theming for the Block Editor", + "slug": "themes", + "markdown_source": "../docs/how-to-guides/themes/README.md", + "parent": "how-to-guides" }, { - "title": "Block-based Themes (Experimental)", - "slug": "block-based-themes", - "markdown_source": "../docs/designers-developers/developers/themes/block-based-themes.md", + "title": "Theme Support", + "slug": "theme-support", + "markdown_source": "../docs/how-to-guides/themes/theme-support.md", "parent": "themes" }, { "title": "Themes & Block Editor: experimental theme.json", "slug": "theme-json", - "markdown_source": "../docs/designers-developers/developers/themes/theme-json.md", + "markdown_source": "../docs/how-to-guides/themes/theme-json.md", "parent": "themes" }, + { + "title": "Creating a block-based theme", + "slug": "block-based-theme", + "markdown_source": "../docs/how-to-guides/block-based-theme/README.md", + "parent": "how-to-guides" + }, + { + "title": "Adding blocks to your theme", + "slug": "block-based-themes-2-adding-blocks", + "markdown_source": "../docs/how-to-guides/block-based-theme/block-based-themes-2-adding-blocks.md", + "parent": "block-based-theme" + }, { "title": "Backward Compatibility", "slug": "backward-compatibility", - "markdown_source": "../docs/designers-developers/developers/backward-compatibility/README.md", - "parent": "developers" + "markdown_source": "../docs/how-to-guides/backward-compatibility/README.md", + "parent": "how-to-guides" }, { "title": "Deprecations", "slug": "deprecations", - "markdown_source": "../docs/designers-developers/developers/backward-compatibility/deprecations.md", + "markdown_source": "../docs/how-to-guides/backward-compatibility/deprecations.md", "parent": "backward-compatibility" }, { "title": "Meta Boxes", "slug": "meta-box", - "markdown_source": "../docs/designers-developers/developers/backward-compatibility/meta-box.md", + "markdown_source": "../docs/how-to-guides/backward-compatibility/meta-box.md", "parent": "backward-compatibility" }, + { + "title": "Introduction to the Format API", + "slug": "format-api", + "markdown_source": "../docs/how-to-guides/format-api/README.md", + "parent": "how-to-guides" + }, + { + "title": "Register a New Format", + "slug": "1-register-format", + "markdown_source": "../docs/how-to-guides/format-api/1-register-format.md", + "parent": "format-api" + }, + { + "title": "Add a Button to the Toolbar", + "slug": "2-toolbar-button", + "markdown_source": "../docs/how-to-guides/format-api/2-toolbar-button.md", + "parent": "format-api" + }, + { + "title": "Apply the Format When the Button Is Clicked", + "slug": "3-apply-format", + "markdown_source": "../docs/how-to-guides/format-api/3-apply-format.md", + "parent": "format-api" + }, { "title": "Gutenberg as a Development Platform", "slug": "platform", - "markdown_source": "../docs/designers-developers/developers/platform/README.md", - "parent": "developers" + "markdown_source": "../docs/how-to-guides/platform/README.md", + "parent": "how-to-guides" }, { "title": "Building a custom block editor", "slug": "custom-block-editor", - "markdown_source": "../docs/designers-developers/developers/platform/custom-block-editor/README.md", + "markdown_source": "../docs/how-to-guides/platform/custom-block-editor/README.md", "parent": "platform" }, { "title": "Tutorial: building a custom block editor", "slug": "tutorial", - "markdown_source": "../docs/designers-developers/developers/platform/custom-block-editor/tutorial.md", + "markdown_source": "../docs/how-to-guides/platform/custom-block-editor/tutorial.md", "parent": "custom-block-editor" }, { "title": "Designer Documentation", "slug": "designers", - "markdown_source": "../docs/designers-developers/designers/README.md", - "parent": null + "markdown_source": "../docs/how-to-guides/designers/README.md", + "parent": "how-to-guides" }, { "title": "Block Design", "slug": "block-design", - "markdown_source": "../docs/designers-developers/designers/block-design.md", + "markdown_source": "../docs/how-to-guides/designers/block-design.md", "parent": "designers" }, { "title": "User Interface", "slug": "user-interface", - "markdown_source": "../docs/designers-developers/designers/user-interface.md", + "markdown_source": "../docs/how-to-guides/designers/user-interface.md", "parent": "designers" }, { "title": "Resources", "slug": "design-resources", - "markdown_source": "../docs/designers-developers/designers/design-resources.md", + "markdown_source": "../docs/how-to-guides/designers/design-resources.md", "parent": "designers" }, { "title": "Animation", "slug": "animation", - "markdown_source": "../docs/designers-developers/designers/animation.md", + "markdown_source": "../docs/how-to-guides/designers/animation.md", "parent": "designers" }, { - "title": "Contributor Guide", - "slug": "contributors", - "markdown_source": "../docs/contributors/readme.md", - "parent": null - }, - { - "title": "Code Contributions", - "slug": "develop", - "markdown_source": "../docs/contributors/develop.md", - "parent": "contributors" - }, - { - "title": "Getting Started", - "slug": "getting-started", - "markdown_source": "../docs/contributors/getting-started.md", - "parent": "develop" - }, - { - "title": "Git Workflow", - "slug": "git-workflow", - "markdown_source": "../docs/contributors/git-workflow.md", - "parent": "develop" - }, - { - "title": "Coding Guidelines", - "slug": "coding-guidelines", - "markdown_source": "../docs/contributors/coding-guidelines.md", - "parent": "develop" - }, - { - "title": "Testing Overview", - "slug": "testing-overview", - "markdown_source": "../docs/contributors/testing-overview.md", - "parent": "develop" - }, - { - "title": "Block Grammar", - "slug": "grammar", - "markdown_source": "../docs/contributors/grammar.md", - "parent": "develop" - }, - { - "title": "Scripts", - "slug": "scripts", - "markdown_source": "../docs/contributors/scripts.md", - "parent": "develop" - }, - { - "title": "Managing Packages", - "slug": "managing-packages", - "markdown_source": "../docs/contributors/managing-packages.md", - "parent": "develop" - }, - { - "title": "Gutenberg Release Process", - "slug": "release", - "markdown_source": "../docs/contributors/release.md", - "parent": "develop" - }, - { - "title": "React Native based mobile Gutenberg", - "slug": "native-mobile", - "markdown_source": "../docs/contributors/native-mobile.md", - "parent": "develop" - }, - { - "title": "Getting Started for the React Native based Mobile Gutenberg", - "slug": "getting-started-native-mobile", - "markdown_source": "../docs/contributors/getting-started-native-mobile.md", - "parent": "develop" - }, - { - "title": "Design Contributions", - "slug": "design", - "markdown_source": "../docs/contributors/design.md", - "parent": "contributors" - }, - { - "title": "Blocks are the Interface", - "slug": "the-block", - "markdown_source": "../docs/contributors/the-block.md", - "parent": "design" - }, - { - "title": "Reference", - "slug": "reference", - "markdown_source": "../docs/contributors/reference.md", - "parent": "design" - }, - { - "title": "Documentation Contributions", - "slug": "document", - "markdown_source": "../docs/contributors/document.md", - "parent": "contributors" - }, - { - "title": "Copy Guidelines", - "slug": "copy-guide", - "markdown_source": "../docs/contributors/copy-guide.md", - "parent": "document" - }, - { - "title": "Triage", - "slug": "triage", - "markdown_source": "../docs/contributors/triage.md", - "parent": "contributors" - }, - { - "title": "Localizing Gutenberg Plugin", - "slug": "localizing", - "markdown_source": "../docs/contributors/localizing.md", - "parent": "contributors" + "title": "Accessibility", + "slug": "accessibility", + "markdown_source": "../docs/how-to-guides/accessibility.md", + "parent": "how-to-guides" }, { - "title": "Repository Management", - "slug": "repository-management", - "markdown_source": "../docs/contributors/repository-management.md", - "parent": "contributors" + "title": "Internationalization", + "slug": "internationalization", + "markdown_source": "../docs/how-to-guides/internationalization.md", + "parent": "how-to-guides" }, { - "title": "Tutorials", - "slug": "tutorials", - "markdown_source": "../docs/designers-developers/developers/tutorials/readme.md", + "title": "Reference Guides", + "slug": "reference-guides", + "markdown_source": "../docs/reference-guides/README.md", "parent": null }, { - "title": "Development Environment", - "slug": "devenv", - "markdown_source": "../docs/designers-developers/developers/tutorials/devenv/readme.md", - "parent": "tutorials" - }, - { - "title": "How to setup local WordPress environment on Ubuntu", - "slug": "docker-ubuntu", - "markdown_source": "../docs/designers-developers/developers/tutorials/devenv/docker-ubuntu.md", - "parent": "devenv" - }, - { - "title": "Getting Started with JavaScript", - "slug": "javascript", - "markdown_source": "../docs/designers-developers/developers/tutorials/javascript/readme.md", - "parent": "tutorials" - }, - { - "title": "Plugins Background", - "slug": "plugins-background", - "markdown_source": "../docs/designers-developers/developers/tutorials/javascript/plugins-background.md", - "parent": "javascript" - }, - { - "title": "Loading JavaScript", - "slug": "loading-javascript", - "markdown_source": "../docs/designers-developers/developers/tutorials/javascript/loading-javascript.md", - "parent": "javascript" - }, - { - "title": "Extending the Block Editor", - "slug": "extending-the-block-editor", - "markdown_source": "../docs/designers-developers/developers/tutorials/javascript/extending-the-block-editor.md", - "parent": "javascript" - }, - { - "title": "Troubleshooting", - "slug": "troubleshooting", - "markdown_source": "../docs/designers-developers/developers/tutorials/javascript/troubleshooting.md", - "parent": "javascript" - }, - { - "title": "JavaScript Versions and Build Step", - "slug": "versions-and-building", - "markdown_source": "../docs/designers-developers/developers/tutorials/javascript/versions-and-building.md", - "parent": "javascript" - }, - { - "title": "Scope Your Code", - "slug": "scope-your-code", - "markdown_source": "../docs/designers-developers/developers/tutorials/javascript/scope-your-code.md", - "parent": "javascript" - }, - { - "title": "JavaScript Build Setup", - "slug": "js-build-setup", - "markdown_source": "../docs/designers-developers/developers/tutorials/javascript/js-build-setup.md", - "parent": "javascript" - }, - { - "title": "ESNext Syntax", - "slug": "esnext-js", - "markdown_source": "../docs/designers-developers/developers/tutorials/javascript/esnext-js.md", - "parent": "javascript" - }, - { - "title": "Create a Block Tutorial", - "slug": "create-block", - "markdown_source": "../docs/designers-developers/developers/tutorials/create-block/readme.md", - "parent": "tutorials" - }, - { - "title": "WordPress Plugin", - "slug": "wp-plugin", - "markdown_source": "../docs/designers-developers/developers/tutorials/create-block/wp-plugin.md", - "parent": "create-block" - }, - { - "title": "Anatomy of a Block", - "slug": "block-anatomy", - "markdown_source": "../docs/designers-developers/developers/tutorials/create-block/block-anatomy.md", - "parent": "create-block" - }, - { - "title": "Block Attributes", - "slug": "attributes", - "markdown_source": "../docs/designers-developers/developers/tutorials/create-block/attributes.md", - "parent": "create-block" - }, - { - "title": "Code Implementation", - "slug": "block-code", - "markdown_source": "../docs/designers-developers/developers/tutorials/create-block/block-code.md", - "parent": "create-block" - }, - { - "title": "Authoring Experience", - "slug": "author-experience", - "markdown_source": "../docs/designers-developers/developers/tutorials/create-block/author-experience.md", - "parent": "create-block" + "title": "Block API Reference", + "slug": "block-api", + "markdown_source": "../docs/reference-guides/block-api/README.md", + "parent": "reference-guides" }, { - "title": "Finishing Touches", - "slug": "finishing", - "markdown_source": "../docs/designers-developers/developers/tutorials/create-block/finishing.md", - "parent": "create-block" + "title": "Block Registration", + "slug": "block-registration", + "markdown_source": "../docs/reference-guides/block-api/block-registration.md", + "parent": "block-api" }, { - "title": "Blocks", - "slug": "block-tutorial", - "markdown_source": "../docs/designers-developers/developers/tutorials/block-tutorial/readme.md", - "parent": "tutorials" + "title": "Edit and Save", + "slug": "block-edit-save", + "markdown_source": "../docs/reference-guides/block-api/block-edit-save.md", + "parent": "block-api" }, { - "title": "Writing Your First Block Type", - "slug": "writing-your-first-block-type", - "markdown_source": "../docs/designers-developers/developers/tutorials/block-tutorial/writing-your-first-block-type.md", - "parent": "block-tutorial" + "title": "Attributes", + "slug": "block-attributes", + "markdown_source": "../docs/reference-guides/block-api/block-attributes.md", + "parent": "block-api" }, { - "title": "Applying Styles From a Stylesheet", - "slug": "applying-styles-with-stylesheets", - "markdown_source": "../docs/designers-developers/developers/tutorials/block-tutorial/applying-styles-with-stylesheets.md", - "parent": "block-tutorial" + "title": "Block Context", + "slug": "block-context", + "markdown_source": "../docs/reference-guides/block-api/block-context.md", + "parent": "block-api" }, { - "title": "Introducing Attributes and Editable Fields", - "slug": "introducing-attributes-and-editable-fields", - "markdown_source": "../docs/designers-developers/developers/tutorials/block-tutorial/introducing-attributes-and-editable-fields.md", - "parent": "block-tutorial" + "title": "Deprecated Blocks", + "slug": "block-deprecation", + "markdown_source": "../docs/reference-guides/block-api/block-deprecation.md", + "parent": "block-api" }, { - "title": "Block Controls: Block Toolbar and Settings Sidebar", - "slug": "block-controls-toolbar-and-sidebar", - "markdown_source": "../docs/designers-developers/developers/tutorials/block-tutorial/block-controls-toolbar-and-sidebar.md", - "parent": "block-tutorial" + "title": "Block Supports", + "slug": "block-supports", + "markdown_source": "../docs/reference-guides/block-api/block-supports.md", + "parent": "block-api" }, { - "title": "Creating dynamic blocks", - "slug": "creating-dynamic-blocks", - "markdown_source": "../docs/designers-developers/developers/tutorials/block-tutorial/creating-dynamic-blocks.md", - "parent": "block-tutorial" + "title": "Block Transforms", + "slug": "block-transforms", + "markdown_source": "../docs/reference-guides/block-api/block-transforms.md", + "parent": "block-api" }, { - "title": "Generate Blocks with WP-CLI", - "slug": "generate-blocks-with-wp-cli", - "markdown_source": "../docs/designers-developers/developers/tutorials/block-tutorial/generate-blocks-with-wp-cli.md", - "parent": "block-tutorial" + "title": "Templates", + "slug": "block-templates", + "markdown_source": "../docs/reference-guides/block-api/block-templates.md", + "parent": "block-api" }, { - "title": "Nested Blocks: Using InnerBlocks", - "slug": "nested-blocks-inner-blocks", - "markdown_source": "../docs/designers-developers/developers/tutorials/block-tutorial/nested-blocks-inner-blocks.md", - "parent": "block-tutorial" + "title": "Block Type Metadata", + "slug": "block-metadata", + "markdown_source": "../docs/reference-guides/block-api/block-metadata.md", + "parent": "block-api" }, { - "title": "Meta Boxes", - "slug": "metabox", - "markdown_source": "../docs/designers-developers/developers/tutorials/metabox/readme.md", - "parent": "tutorials" + "title": "Block Variations", + "slug": "block-variations", + "markdown_source": "../docs/reference-guides/block-api/block-variations.md", + "parent": "block-api" }, { - "title": "Store Post Meta with a Block", - "slug": "meta-block-1-intro", - "markdown_source": "../docs/designers-developers/developers/tutorials/metabox/meta-block-1-intro.md", - "parent": "metabox" + "title": "Block Patterns", + "slug": "block-patterns", + "markdown_source": "../docs/reference-guides/block-api/block-patterns.md", + "parent": "block-api" }, { - "title": "Register Meta Field", - "slug": "meta-block-2-register-meta", - "markdown_source": "../docs/designers-developers/developers/tutorials/metabox/meta-block-2-register-meta.md", - "parent": "metabox" + "title": "Annotations", + "slug": "block-annotations", + "markdown_source": "../docs/reference-guides/block-api/block-annotations.md", + "parent": "block-api" }, { - "title": "Create Meta Block", - "slug": "meta-block-3-add", - "markdown_source": "../docs/designers-developers/developers/tutorials/metabox/meta-block-3-add.md", - "parent": "metabox" + "title": "Block API Versions", + "slug": "versions", + "markdown_source": "../docs/reference-guides/block-api/versions.md", + "parent": "block-api" }, { - "title": "Use Post Meta Data", - "slug": "meta-block-4-use-data", - "markdown_source": "../docs/designers-developers/developers/tutorials/metabox/meta-block-4-use-data.md", - "parent": "metabox" + "title": "Filter Reference", + "slug": "filters", + "markdown_source": "../docs/reference-guides/filters/README.md", + "parent": "reference-guides" }, { - "title": "Finishing Touches", - "slug": "meta-block-5-finishing", - "markdown_source": "../docs/designers-developers/developers/tutorials/metabox/meta-block-5-finishing.md", - "parent": "metabox" + "title": "Block Filters", + "slug": "block-filters", + "markdown_source": "../docs/reference-guides/filters/block-filters.md", + "parent": "filters" }, { - "title": "Displaying Notices from Your Plugin or Theme", - "slug": "notices", - "markdown_source": "../docs/designers-developers/developers/tutorials/notices/README.md", - "parent": "tutorials" + "title": "Editor Filters", + "slug": "editor-filters", + "markdown_source": "../docs/reference-guides/filters/editor-filters.md", + "parent": "filters" }, { - "title": "Creating a Sidebar for Your Plugin", - "slug": "plugin-sidebar-0", - "markdown_source": "../docs/designers-developers/developers/tutorials/sidebar-tutorial/plugin-sidebar-0.md", - "parent": "tutorials" + "title": "Parser Filters", + "slug": "parser-filters", + "markdown_source": "../docs/reference-guides/filters/parser-filters.md", + "parent": "filters" }, { - "title": "Get a Sidebar up and Running", - "slug": "plugin-sidebar-1-up-and-running", - "markdown_source": "../docs/designers-developers/developers/tutorials/sidebar-tutorial/plugin-sidebar-1-up-and-running.md", - "parent": "plugin-sidebar-0" + "title": "Autocomplete", + "slug": "autocomplete-filters", + "markdown_source": "../docs/reference-guides/filters/autocomplete-filters.md", + "parent": "filters" }, { - "title": "Tweak the sidebar style and add controls", - "slug": "plugin-sidebar-2-styles-and-controls", - "markdown_source": "../docs/designers-developers/developers/tutorials/sidebar-tutorial/plugin-sidebar-2-styles-and-controls.md", - "parent": "plugin-sidebar-0" + "title": "SlotFills Reference", + "slug": "slotfills", + "markdown_source": "../docs/reference-guides/slotfills/README.md", + "parent": "reference-guides" }, { - "title": "Register the Meta Field", - "slug": "plugin-sidebar-3-register-meta", - "markdown_source": "../docs/designers-developers/developers/tutorials/sidebar-tutorial/plugin-sidebar-3-register-meta.md", - "parent": "plugin-sidebar-0" + "title": "MainDashboardButton", + "slug": "main-dashboard-button", + "markdown_source": "../docs/reference-guides/slotfills/main-dashboard-button.md", + "parent": "slotfills" }, { - "title": "Initialize the Input Control", - "slug": "plugin-sidebar-4-initialize-input", - "markdown_source": "../docs/designers-developers/developers/tutorials/sidebar-tutorial/plugin-sidebar-4-initialize-input.md", - "parent": "plugin-sidebar-0" + "title": "PluginBlockSettingsMenuItem", + "slug": "plugin-block-settings-menu-item", + "markdown_source": "../docs/reference-guides/slotfills/plugin-block-settings-menu-item.md", + "parent": "slotfills" }, { - "title": "Update the Meta Field When the Input's Content Changes", - "slug": "plugin-sidebar-5-update-meta", - "markdown_source": "../docs/designers-developers/developers/tutorials/sidebar-tutorial/plugin-sidebar-5-update-meta.md", - "parent": "plugin-sidebar-0" + "title": "PluginDocumentSettingPanel", + "slug": "plugin-document-setting-panel", + "markdown_source": "../docs/reference-guides/slotfills/plugin-document-setting-panel.md", + "parent": "slotfills" }, { - "title": "Finishing Touches", - "slug": "plugin-sidebar-6-finishing-touches", - "markdown_source": "../docs/designers-developers/developers/tutorials/sidebar-tutorial/plugin-sidebar-6-finishing-touches.md", - "parent": "plugin-sidebar-0" + "title": "PluginMoreMenuItem", + "slug": "plugin-more-menu-item", + "markdown_source": "../docs/reference-guides/slotfills/plugin-more-menu-item.md", + "parent": "slotfills" }, { - "title": "Introduction to the Format API", - "slug": "format-api", - "markdown_source": "../docs/designers-developers/developers/tutorials/format-api/README.md", - "parent": "tutorials" + "title": "PluginPostPublishPanel", + "slug": "plugin-post-publish-panel", + "markdown_source": "../docs/reference-guides/slotfills/plugin-post-publish-panel.md", + "parent": "slotfills" }, { - "title": "Register a New Format", - "slug": "1-register-format", - "markdown_source": "../docs/designers-developers/developers/tutorials/format-api/1-register-format.md", - "parent": "format-api" + "title": "PluginPostStatusInfo", + "slug": "plugin-post-status-info", + "markdown_source": "../docs/reference-guides/slotfills/plugin-post-status-info.md", + "parent": "slotfills" }, { - "title": "Add a Button to the Toolbar", - "slug": "2-toolbar-button", - "markdown_source": "../docs/designers-developers/developers/tutorials/format-api/2-toolbar-button.md", - "parent": "format-api" + "title": "PluginPrePublishPanel", + "slug": "plugin-pre-publish-panel", + "markdown_source": "../docs/reference-guides/slotfills/plugin-pre-publish-panel.md", + "parent": "slotfills" }, { - "title": "Apply the Format When the Button Is Clicked", - "slug": "3-apply-format", - "markdown_source": "../docs/designers-developers/developers/tutorials/format-api/3-apply-format.md", - "parent": "format-api" + "title": "PluginSidebar", + "slug": "plugin-sidebar", + "markdown_source": "../docs/reference-guides/slotfills/plugin-sidebar.md", + "parent": "slotfills" }, { - "title": "Creating a block-based theme", - "slug": "block-based-themes", - "markdown_source": "../docs/designers-developers/developers/tutorials/block-based-themes/README.md", - "parent": "tutorials" + "title": "PluginSidebarMoreMenuItem", + "slug": "plugin-sidebar-more-menu-item", + "markdown_source": "../docs/reference-guides/slotfills/plugin-sidebar-more-menu-item.md", + "parent": "slotfills" }, - { - "title": "Adding blocks to your theme", - "slug": "block-based-themes-2-adding-blocks", - "markdown_source": "../docs/designers-developers/developers/tutorials/block-based-themes/block-based-themes-2-adding-blocks.md", - "parent": "block-based-themes" + { + "title": "RichText Reference", + "slug": "richtext", + "markdown_source": "../docs/reference-guides/richtext.md", + "parent": "reference-guides" }, { "title": "Component Reference", "slug": "components", "markdown_source": "../packages/components/README.md", - "parent": null + "parent": "reference-guides" }, { "title": "AlignmentMatrixControl", @@ -1067,12 +911,6 @@ "markdown_source": "../packages/components/src/menu-items-choice/README.md", "parent": "components" }, - { - "title": "BottomSheetNavigation", - "slug": "bottom-sheet-navigation", - "markdown_source": "../packages/components/src/mobile/bottom-sheet/bottom-sheet-navigation/README.md", - "parent": "components" - }, { "title": "Modal", "slug": "modal", @@ -1289,71 +1127,11 @@ "markdown_source": "../packages/components/src/visually-hidden/README.md", "parent": "components" }, - { - "title": "Data Module Reference", - "slug": "data", - "markdown_source": "../docs/designers-developers/developers/data/README.md", - "parent": null - }, - { - "title": "WordPress Core Data", - "slug": "data-core", - "markdown_source": "../docs/designers-developers/developers/data/data-core.md", - "parent": "data" - }, - { - "title": "Annotations", - "slug": "data-core-annotations", - "markdown_source": "../docs/designers-developers/developers/data/data-core-annotations.md", - "parent": "data" - }, - { - "title": "Block Types Data", - "slug": "data-core-blocks", - "markdown_source": "../docs/designers-developers/developers/data/data-core-blocks.md", - "parent": "data" - }, - { - "title": "The Block Editor’s Data", - "slug": "data-core-block-editor", - "markdown_source": "../docs/designers-developers/developers/data/data-core-block-editor.md", - "parent": "data" - }, - { - "title": "The Post Editor’s Data", - "slug": "data-core-editor", - "markdown_source": "../docs/designers-developers/developers/data/data-core-editor.md", - "parent": "data" - }, - { - "title": "The Editor’s UI Data", - "slug": "data-core-edit-post", - "markdown_source": "../docs/designers-developers/developers/data/data-core-edit-post.md", - "parent": "data" - }, - { - "title": "Notices Data", - "slug": "data-core-notices", - "markdown_source": "../docs/designers-developers/developers/data/data-core-notices.md", - "parent": "data" - }, - { - "title": "The NUX (New User Experience) Data", - "slug": "data-core-nux", - "markdown_source": "../docs/designers-developers/developers/data/data-core-nux.md", - "parent": "data" - }, - { - "title": "The Viewport Data", - "slug": "data-core-viewport", - "markdown_source": "../docs/designers-developers/developers/data/data-core-viewport.md", - "parent": "data" - }, { "title": "Package Reference", "slug": "packages", - "markdown_source": "../docs/designers-developers/developers/packages.md", - "parent": null + "markdown_source": "../docs/reference-guides/packages.md", + "parent": "reference-guides" }, { "title": "@wordpress/a11y", @@ -1469,6 +1247,12 @@ "markdown_source": "../packages/core-data/README.md", "parent": "packages" }, + { + "title": "@wordpress/create-block-tutorial-template", + "slug": "packages-create-block-tutorial-template", + "markdown_source": "../packages/create-block-tutorial-template/README.md", + "parent": "packages" + }, { "title": "@wordpress/create-block", "slug": "packages-create-block", @@ -1481,6 +1265,12 @@ "markdown_source": "../packages/custom-templated-path-webpack-plugin/README.md", "parent": "packages" }, + { + "title": "@wordpress/customize-widgets", + "slug": "packages-customize-widgets", + "markdown_source": "../packages/customize-widgets/README.md", + "parent": "packages" + }, { "title": "@wordpress/data-controls", "slug": "packages-data-controls", @@ -1751,6 +1541,12 @@ "markdown_source": "../packages/project-management-automation/README.md", "parent": "packages" }, + { + "title": "@wordpress/react-i18n", + "slug": "packages-react-i18n", + "markdown_source": "../packages/react-i18n/README.md", + "parent": "packages" + }, { "title": "@wordpress/react-native-aztec", "slug": "packages-react-native-aztec", @@ -1840,5 +1636,257 @@ "slug": "packages-wordcount", "markdown_source": "../packages/wordcount/README.md", "parent": "packages" + }, + { + "title": "Data Module Reference", + "slug": "data", + "markdown_source": "../docs/reference-guides/data/README.md", + "parent": "reference-guides" + }, + { + "title": "WordPress Core Data", + "slug": "data-core", + "markdown_source": "../docs/reference-guides/data/data-core.md", + "parent": "data" + }, + { + "title": "Annotations", + "slug": "data-core-annotations", + "markdown_source": "../docs/reference-guides/data/data-core-annotations.md", + "parent": "data" + }, + { + "title": "Block Types Data", + "slug": "data-core-blocks", + "markdown_source": "../docs/reference-guides/data/data-core-blocks.md", + "parent": "data" + }, + { + "title": "The Block Editor’s Data", + "slug": "data-core-block-editor", + "markdown_source": "../docs/reference-guides/data/data-core-block-editor.md", + "parent": "data" + }, + { + "title": "The Post Editor’s Data", + "slug": "data-core-editor", + "markdown_source": "../docs/reference-guides/data/data-core-editor.md", + "parent": "data" + }, + { + "title": "The Editor’s UI Data", + "slug": "data-core-edit-post", + "markdown_source": "../docs/reference-guides/data/data-core-edit-post.md", + "parent": "data" + }, + { + "title": "Notices Data", + "slug": "data-core-notices", + "markdown_source": "../docs/reference-guides/data/data-core-notices.md", + "parent": "data" + }, + { + "title": "The NUX (New User Experience) Data", + "slug": "data-core-nux", + "markdown_source": "../docs/reference-guides/data/data-core-nux.md", + "parent": "data" + }, + { + "title": "The Viewport Data", + "slug": "data-core-viewport", + "markdown_source": "../docs/reference-guides/data/data-core-viewport.md", + "parent": "data" + }, + { + "title": "Explanations", + "slug": "explanations", + "markdown_source": "../docs/explanations/README.md", + "parent": null + }, + { + "title": "Architecture", + "slug": "architecture", + "markdown_source": "../docs/explanations/architecture/README.md", + "parent": "explanations" + }, + { + "title": "Key Concepts", + "slug": "key-concepts", + "markdown_source": "../docs/explanations/architecture/key-concepts.md", + "parent": "architecture" + }, + { + "title": "Data Flow and Data Format", + "slug": "data-flow", + "markdown_source": "../docs/explanations/architecture/data-flow.md", + "parent": "architecture" + }, + { + "title": "Modularity", + "slug": "modularity", + "markdown_source": "../docs/explanations/architecture/modularity.md", + "parent": "architecture" + }, + { + "title": "Performance", + "slug": "performance", + "markdown_source": "../docs/explanations/architecture/performance.md", + "parent": "architecture" + }, + { + "title": "Automated Testing", + "slug": "automated-testing", + "markdown_source": "../docs/explanations/architecture/automated-testing.md", + "parent": "architecture" + }, + { + "title": "Full Site Editing Templates", + "slug": "full-site-editing-templates", + "markdown_source": "../docs/explanations/architecture/full-site-editing-templates.md", + "parent": "architecture" + }, + { + "title": "Contributor Guide", + "slug": "contributors", + "markdown_source": "../docs/contributors/README.md", + "parent": null + }, + { + "title": "Code Contributions", + "slug": "code", + "markdown_source": "../docs/contributors/code/README.md", + "parent": "contributors" + }, + { + "title": "Getting Started With Code Contribution", + "slug": "getting-started-with-code-contribution", + "markdown_source": "../docs/contributors/code/getting-started-with-code-contribution.md", + "parent": "code" + }, + { + "title": "Git Workflow", + "slug": "git-workflow", + "markdown_source": "../docs/contributors/code/git-workflow.md", + "parent": "code" + }, + { + "title": "Coding Guidelines", + "slug": "coding-guidelines", + "markdown_source": "../docs/contributors/code/coding-guidelines.md", + "parent": "code" + }, + { + "title": "Testing Overview", + "slug": "testing-overview", + "markdown_source": "../docs/contributors/code/testing-overview.md", + "parent": "code" + }, + { + "title": "Block Grammar", + "slug": "grammar", + "markdown_source": "../docs/contributors/code/grammar.md", + "parent": "code" + }, + { + "title": "Scripts", + "slug": "scripts", + "markdown_source": "../docs/contributors/code/scripts.md", + "parent": "code" + }, + { + "title": "Managing Packages", + "slug": "managing-packages", + "markdown_source": "../docs/contributors/code/managing-packages.md", + "parent": "code" + }, + { + "title": "Gutenberg Release Process", + "slug": "release", + "markdown_source": "../docs/contributors/code/release.md", + "parent": "code" + }, + { + "title": "React Native based mobile Gutenberg", + "slug": "native-mobile", + "markdown_source": "../docs/contributors/code/native-mobile.md", + "parent": "code" + }, + { + "title": "Getting Started for the React Native based Mobile Gutenberg", + "slug": "getting-started-native-mobile", + "markdown_source": "../docs/contributors/code/getting-started-native-mobile.md", + "parent": "code" + }, + { + "title": "Design Contributions", + "slug": "design", + "markdown_source": "../docs/contributors/design/README.md", + "parent": "contributors" + }, + { + "title": "Blocks are the Interface", + "slug": "the-block", + "markdown_source": "../docs/contributors/design/the-block.md", + "parent": "design" + }, + { + "title": "Reference", + "slug": "reference", + "markdown_source": "../docs/contributors/design/reference.md", + "parent": "design" + }, + { + "title": "Documentation Contributions", + "slug": "documentation", + "markdown_source": "../docs/contributors/documentation/README.md", + "parent": "contributors" + }, + { + "title": "Copy Guidelines", + "slug": "copy-guide", + "markdown_source": "../docs/contributors/documentation/copy-guide.md", + "parent": "documentation" + }, + { + "title": "Triage", + "slug": "triage", + "markdown_source": "../docs/contributors/triage.md", + "parent": "contributors" + }, + { + "title": "Localizing Gutenberg Plugin", + "slug": "localizing", + "markdown_source": "../docs/contributors/localizing.md", + "parent": "contributors" + }, + { + "title": "Accessibility Testing", + "slug": "accessibility-testing", + "markdown_source": "../docs/contributors/accessibility-testing.md", + "parent": "contributors" + }, + { + "title": "Repository Management", + "slug": "repository-management", + "markdown_source": "../docs/contributors/repository-management.md", + "parent": "contributors" + }, + { + "title": "Folder Structure", + "slug": "folder-structure", + "markdown_source": "../docs/contributors/folder-structure.md", + "parent": "contributors" + }, + { + "title": "Versions in WordPress", + "slug": "versions-in-wordpress", + "markdown_source": "../docs/contributors/versions-in-wordpress.md", + "parent": "contributors" + }, + { + "title": "Upcoming Projects & Roadmap", + "slug": "roadmap", + "markdown_source": "../docs/contributors/roadmap.md", + "parent": "contributors" } ] \ No newline at end of file diff --git a/docs/readme.md b/docs/readme.md deleted file mode 100644 index 0b34e013a00b4c..00000000000000 --- a/docs/readme.md +++ /dev/null @@ -1,23 +0,0 @@ -# Project Overview - -The Gutenberg project is transforming the way content is created on WordPress. A block editor was the first product launched creating a new methodology for working with content. - -The Block Editor handbook provides documentation for designers and developers on how to extend the editor, and also how you can start contributing to the project. For authors, writers, and users of the block editor see the [block editor support documentation](https://wordpress.org/support/article/wordpress-editor/). - -![Gutenberg Demo](https://cldup.com/kZXGDcGPMU.gif) - -Using a system of Blocks to compose and format content, the new block-based editor is designed to create rich, flexible layouts for websites and digital products. Content is created in the unit of blocks instead of freeform text with inserted media, embeds and Shortcodes (there's a Shortcode block though). - -Blocks treat Paragraphs, Headings, Media, and Embeds all as components that, when strung together, make up the content stored in the WordPress database, replacing the traditional concept of freeform text with embedded media and shortcodes. The new editor is designed with progressive enhancement, meaning that it is back-compatible with all legacy content, and it also offers a process to try to convert and split a Classic block into equivalent blocks using client-side parsing. Finally, the blocks offer enhanced editing and format controls. - -The Editor offers rich new value to users with visual, drag-and-drop creation tools and powerful developer enhancements with modern vendor packages, reusable components, rich APIs and hooks to modify and extend the editor through Custom Blocks, Custom Block Styles and Plugins. - -## Quick Links - -- Beginners: The [Create a Block Tutorial](/docs/designers-developers/developers/tutorials/create-block/readme.md) walks through creating a block plugin using the `@wordpress/create-block` package; a quick and easy way to start creating your own block. - -- [Gutenberg Architecture](/docs/architecture/readme.md) covers the conceptual and tool choices going into the Gutenberg project, from repository structure to packages and tools. - -- [Block API Reference](/docs/designers-developers/developers/block-api/README.md) - -- [Contributors Guide](/docs/contributors/readme.md) covers how **you** can help; be it code, design, documentation, language, or triage, we need you to help make Gutenberg. diff --git a/docs/reference-guides/README.md b/docs/reference-guides/README.md new file mode 100644 index 00000000000000..37cc9b8fc77ca5 --- /dev/null +++ b/docs/reference-guides/README.md @@ -0,0 +1,54 @@ +# Reference Guides + +## [Block API Reference](/docs/reference-guides/block-api/README.md) + +- [Block registration](/docs/reference-guides/block-api/block-registration.md) +- [Edit and Save](/docs/reference-guides/block-api/block-edit-save.md) +- [Attributes](/docs/reference-guides/block-api/block-attributes.md) +- [Context](/docs/reference-guides/block-api/block-context.md) +- [Deprecation](/docs/reference-guides/block-api/block-deprecation.md) +- [Supports](/docs/reference-guides/block-api/block-supports.md) +- [Transformations](/docs/reference-guides/block-api/block-transforms.md) +- [Templates](/docs/reference-guides/block-api/block-templates.md) +- [Metadata](/docs/reference-guides/block-api/block-metadata.md) +- [Block Variations](/docs/reference-guides/block-api/block-variations.md) +- [Block Patterns](/docs/reference-guides/block-api/block-patterns.md) +- [Annotations](/docs/reference-guides/block-api/block-annotations.md) +- [Versions](/docs/reference-guides/block-api/versions.md) + +## [Filter Reference](/docs/reference-guides/filters/README.md) + +- [Block Filters](/docs/reference-guides/filters/block-filters.md) +- [Editor Filters (Experimental)](/docs/reference-guides/filters/editor-filters.md) +- [Parser Filters](/docs/reference-guides/filters/parser-filters.md) +- [Autocomplete](/docs/reference-guides/filters/autocomplete-filters.md) + +## [SlotFills Reference](/docs/reference-guides/slotfills/README.md) + +- [MainDashboardButton](/docs/reference-guides/slotfills/main-dashboard-button.md) +- [PluginBlockSettingsMenuItem](/docs/reference-guides/slotfills/plugin-block-settings-menu-item.md) +- [PluginDocumentSettingPanel](/docs/reference-guides/slotfills/plugin-document-setting-panel.md) +- [PluginMoreMenuItem](/docs/reference-guides/slotfills/plugin-more-menu-item.md) +- [PluginPostPublishPanel](/docs/reference-guides/slotfills/plugin-post-publish-panel.md) +- [PluginPostStatusInfo](/docs/reference-guides/slotfills/plugin-post-status-info.md) +- [PluginPrePublishPanel](/docs/reference-guides/slotfills/plugin-pre-publish-panel.md) +- [PluginSidebar](/docs/reference-guides/slotfills/plugin-sidebar.md) +- [PluginSidebarMoreMenuItem](/docs/reference-guides/slotfills/plugin-sidebar-more-menu-item.md) + +## [RichText Reference](/docs/reference-guides/richtext.md) + +## [Component Reference](/packages/components/README.md) + +## [Package Reference](/docs/reference-guides/packages.md) + +## [Data Module Reference](/docs/reference-guides/data/README.md) + +- [**core**: WordPress Core Data](/docs/reference-guides/data/data-core.md) + - [**core/annotations**: Annotations](/docs/reference-guides/data/data-core-annotations.md) + - [**core/blocks**: Block Types Data](/docs/reference-guides/data/data-core-blocks.md) + - [**core/block-editor**: The Block Editor’s Data](/docs/reference-guides/data/data-core-block-editor.md) + - [**core/editor**: The Post Editor’s Data](/docs/reference-guides/data/data-core-editor.md) + - [**core/edit-post**: The Editor’s UI Data](/docs/reference-guides/data/data-core-edit-post.md) + - [**core/notices**: Notices Data](/docs/reference-guides/data/data-core-notices.md) + - [**core/nux**: The NUX (New User Experience) Data](/docs/reference-guides/data/data-core-nux.md) + - [**core/viewport**: The Viewport Data](/docs/reference-guides/data/data-core-viewport.md) diff --git a/docs/reference-guides/block-api/README.md b/docs/reference-guides/block-api/README.md new file mode 100644 index 00000000000000..7769a442740a78 --- /dev/null +++ b/docs/reference-guides/block-api/README.md @@ -0,0 +1,19 @@ +# Block API Reference + +Blocks are the fundamental element of the editor. They are the primary way in which plugins and themes can register their own functionality and extend the capabilities of the editor. + +The following sections will walk you through the existing block APIs: + +- [Block registration](/docs/reference-guides/block-api/block-registration.md) +- [Edit and Save](/docs/reference-guides/block-api/block-edit-save.md) +- [Attributes](/docs/reference-guides/block-api/block-attributes.md) +- [Context](/docs/reference-guides/block-api/block-context.md) +- [Deprecation](/docs/reference-guides/block-api/block-deprecation.md) +- [Supports](/docs/reference-guides/block-api/block-supports.md) +- [Transformations](/docs/reference-guides/block-api/block-transforms.md) +- [Templates](/docs/reference-guides/block-api/block-templates.md) +- [Metadata](/docs/reference-guides/block-api/block-metadata.md) +- [Block Variations](/docs/reference-guides/block-api/block-variations.md) +- [Block Patterns](/docs/reference-guides/block-api/block-patterns.md) +- [Annotations](/docs/reference-guides/block-api/block-annotations.md) +- [Versions](/docs/reference-guides/block-api/versions.md) diff --git a/docs/designers-developers/developers/block-api/block-annotations.md b/docs/reference-guides/block-api/block-annotations.md similarity index 100% rename from docs/designers-developers/developers/block-api/block-annotations.md rename to docs/reference-guides/block-api/block-annotations.md diff --git a/docs/designers-developers/developers/block-api/block-attributes.md b/docs/reference-guides/block-api/block-attributes.md similarity index 97% rename from docs/designers-developers/developers/block-api/block-attributes.md rename to docs/reference-guides/block-api/block-attributes.md index dd482fd49e5c95..b5cdb3399b3380 100644 --- a/docs/designers-developers/developers/block-api/block-attributes.md +++ b/docs/reference-guides/block-api/block-attributes.md @@ -20,7 +20,7 @@ See [WordPress's REST API documentation](https://developer.wordpress.org/rest-ap Attribute sources are used to define how the block attribute values are extracted from saved post content. They provide a mechanism to map from the saved markup to a JavaScript representation of a block. -If no attribute source is specified, the attribute will be saved to (and read from) the block's [comment delimiter](/docs/designers-developers/key-concepts.md#delimiters-and-parsing-expression-grammar). +If no attribute source is specified, the attribute will be saved to (and read from) the block's [comment delimiter](/docs/getting-started/architecture/key-concepts.md#delimiters-and-parsing-expression-grammar). The keys specified in the attributes source object are named as you see fit. The result of the attribute source definition is assigned as a value to each key. diff --git a/docs/designers-developers/developers/block-api/block-context.md b/docs/reference-guides/block-api/block-context.md similarity index 100% rename from docs/designers-developers/developers/block-api/block-context.md rename to docs/reference-guides/block-api/block-context.md diff --git a/docs/designers-developers/developers/block-api/block-deprecation.md b/docs/reference-guides/block-api/block-deprecation.md similarity index 90% rename from docs/designers-developers/developers/block-api/block-deprecation.md rename to docs/reference-guides/block-api/block-deprecation.md index d598a157d4ab71..e15f1a76cde0de 100644 --- a/docs/designers-developers/developers/block-api/block-deprecation.md +++ b/docs/reference-guides/block-api/block-deprecation.md @@ -33,13 +33,13 @@ var deprecated = [ v3, v2, v1 ]; ``` {% end %} -It is also recommended to keep [fixtures](https://github.com/WordPress/gutenberg/blob/master/packages/e2e-tests/fixtures/blocks/README.md) which contain the different versions of the block content to allow you to easily test that new deprecations and migrations are working across all previous versions of the block. +It is also recommended to keep [fixtures](https://github.com/WordPress/gutenberg/blob/HEAD/packages/e2e-tests/fixtures/blocks/README.md) which contain the different versions of the block content to allow you to easily test that new deprecations and migrations are working across all previous versions of the block. Deprecations are defined on a block type as its `deprecated` property, an array of deprecation objects where each object takes the form: -- `attributes` (Object): The [attributes definition](/docs/designers-developers/developers/block-api/block-attributes.md) of the deprecated form of the block. -- `supports` (Object): The [supports definition](/docs/designers-developers/developers/block-api/block-registration.md) of the deprecated form of the block. -- `save` (Function): The [save implementation](/docs/designers-developers/developers/block-api/block-edit-save.md) of the deprecated form of the block. +- `attributes` (Object): The [attributes definition](/docs/reference-guides/block-api/block-attributes.md) of the deprecated form of the block. +- `supports` (Object): The [supports definition](/docs/reference-guides/block-api/block-registration.md) of the deprecated form of the block. +- `save` (Function): The [save implementation](/docs/reference-guides/block-api/block-edit-save.md) of the deprecated form of the block. - `migrate` (Function, Optional): A function which, given the old attributes and inner blocks is expected to return either the new attributes or a tuple array of `[ attributes, innerBlocks ]` compatible with the block. As mentioned above, a deprecation's `migrate` will not be run if its `save` function does not return a valid block so you will need to make sure your migrations are available in all the deprecations where they are relevant. - `isEligible` (Function, Optional): A function which, given the attributes and inner blocks of the parsed block, returns true if the deprecation can handle the block migration even if the block is valid. This is particularly useful in cases where a block is technically valid even once deprecated, and requires updates to its attributes or inner blocks. This function is not called when the results of all previous deprecations' `save` functions were invalid. @@ -305,4 +305,4 @@ registerBlockType( 'gutenberg/block-with-deprecated-version', { In the example above we updated the block to use an inner Paragraph block with a title instead of a title attribute. -*Above are example cases of block deprecation. For more, real-world examples, check for deprecations in the [core block library](https://github.com/WordPress/gutenberg/tree/master/packages/block-library/src). Core blocks have been updated across releases and contain simple and complex deprecations.* +*Above are example cases of block deprecation. For more, real-world examples, check for deprecations in the [core block library](https://github.com/WordPress/gutenberg/tree/HEAD/packages/block-library/src). Core blocks have been updated across releases and contain simple and complex deprecations.* diff --git a/docs/designers-developers/developers/block-api/block-edit-save.md b/docs/reference-guides/block-api/block-edit-save.md similarity index 90% rename from docs/designers-developers/developers/block-api/block-edit-save.md rename to docs/reference-guides/block-api/block-edit-save.md index d51ae9f7820581..0e56151c381b36 100644 --- a/docs/designers-developers/developers/block-api/block-edit-save.md +++ b/docs/reference-guides/block-api/block-edit-save.md @@ -92,7 +92,7 @@ var blockSettings = { The `edit` function also receives a number of properties through an object argument. You can use these properties to adapt the behavior of your block. -The `attributes` property surfaces all the available attributes and their corresponding values, as described by the `attributes` property when the block type was registered. See [attributes documentation](/docs/designers-developers/developers/block-api/block-attributes.md) for how to specify attribute sources. +The `attributes` property surfaces all the available attributes and their corresponding values, as described by the `attributes` property when the block type was registered. See [attributes documentation](/docs/reference-guides/block-api/block-attributes.md) for how to specify attribute sources. In this case, assuming we had defined an attribute of `content` during block registration, we would receive and use that value in our edit function: @@ -285,10 +285,10 @@ _Note:_ The save function should be a pure function that depends only on the att It can not have any side effect or retrieve information from another source, e.g. it is not possible to use the data module inside it `select( store ).selector( ... )`. This is because if the external information changes, the block may be flagged as invalid when the post is later edited ([read more about Validation](#validation)). If there is a need to have other information as part of the save, developers can consider one of these two alternatives: - - Use [dynamic blocks](/docs/designers-developers/developers/tutorials/block-tutorial/creating-dynamic-blocks.md) and dynamically retrieve the required information on the server. + - Use [dynamic blocks](/docs/how-to-guides/block-tutorial/creating-dynamic-blocks.md) and dynamically retrieve the required information on the server. - Store the external value as an attribute which is dynamically updated in the block's `edit` function as changes occur. -For [dynamic blocks](/docs/designers-developers/developers/tutorials/block-tutorial/creating-dynamic-blocks.md), the return value of `save` could represent a cached copy of the block's content to be shown only in case the plugin implementing the block is ever disabled. +For [dynamic blocks](/docs/how-to-guides/block-tutorial/creating-dynamic-blocks.md), the return value of `save` could represent a cached copy of the block's content to be shown only in case the plugin implementing the block is ever disabled. If left unspecified, the default implementation will save no markup in post content for the dynamic block, instead deferring this to always be calculated when the block is shown on the front of the site. @@ -324,11 +324,11 @@ save: function( props ) { {% end %} -When saving your block, you want to save the attributes in the same format specified by the attribute source definition. If no attribute source is specified, the attribute will be saved to the block's comment delimiter. See the [Block Attributes documentation](/docs/designers-developers/developers/block-api/block-attributes.md) for more details. +When saving your block, you want to save the attributes in the same format specified by the attribute source definition. If no attribute source is specified, the attribute will be saved to the block's comment delimiter. See the [Block Attributes documentation](/docs/reference-guides/block-api/block-attributes.md) for more details. ## Examples -Here are a couple examples of using attributes, edit, and save all together. For a full working example, see the [Introducing Attributes and Editable Fields](/docs/designers-developers/developers/tutorials/block-tutorial/introducing-attributes-and-editable-fields.md) section of the Block Tutorial. +Here are a couple examples of using attributes, edit, and save all together. For a full working example, see the [Introducing Attributes and Editable Fields](/docs/how-to-guides/block-tutorial/introducing-attributes-and-editable-fields.md) section of the Block Tutorial. ### Saving Attributes to Child Elements @@ -408,7 +408,7 @@ save: function( props ) { Ideally, the attributes saved should be included in the markup. However, there are times when this is not practical, so if no attribute source is specified the attribute is serialized and saved to the block's comment delimiter. -This example could be for a dynamic block, such as the [Latest Posts block](https://github.com/WordPress/gutenberg/blob/master/packages/block-library/src/latest-posts/index.js), which renders the markup server-side. The save function is still required, however in this case it simply returns null since the block is not saving content from the editor. +This example could be for a dynamic block, such as the [Latest Posts block](https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-library/src/latest-posts/index.js), which renders the markup server-side. The save function is still required, however in this case it simply returns null since the block is not saving content from the editor. {% codetabs %} {% ESNext %} @@ -504,10 +504,10 @@ The two most common sources of block invalidations are: Before starting to debug, be sure to familiarize yourself with the validation step described above documenting the process for detecting whether a block is invalid. A block is invalid if its regenerated markup does not match what is saved in post content, so often this can be caused by the attributes of a block being parsed incorrectly from the saved content. -If you're using [attribute sources](/docs/designers-developers/developers/block-api/block-attributes.md), be sure that attributes sourced from markup are saved exactly as you expect, and in the correct type (usually a `'string'` or `'number'`). +If you're using [attribute sources](/docs/reference-guides/block-api/block-attributes.md), be sure that attributes sourced from markup are saved exactly as you expect, and in the correct type (usually a `'string'` or `'number'`). When a block is detected as invalid, a warning will be logged into your browser's developer tools console. The warning will include specific details about the exact point at which a difference in markup occurred. Be sure to look closely at any differences in the expected and actual markups to see where problems are occurring. **I've changed my block's `save` behavior and old content now includes invalid blocks. How can I fix this?** -Refer to the guide on [Deprecated Blocks](/docs/designers-developers/developers/block-api/block-deprecation.md) to learn more about how to accommodate legacy content in intentional markup changes. +Refer to the guide on [Deprecated Blocks](/docs/reference-guides/block-api/block-deprecation.md) to learn more about how to accommodate legacy content in intentional markup changes. diff --git a/docs/designers-developers/developers/block-api/block-metadata.md b/docs/reference-guides/block-api/block-metadata.md similarity index 79% rename from docs/designers-developers/developers/block-api/block-metadata.md rename to docs/reference-guides/block-api/block-metadata.md index 24d1468121ba29..8ef4491e9756cd 100644 --- a/docs/designers-developers/developers/block-api/block-metadata.md +++ b/docs/reference-guides/block-api/block-metadata.md @@ -32,7 +32,7 @@ To register a new block type using metadata that can be shared between codebase }, "usesContext": [ "groupId" ], "supports": { - "align": true, + "align": true }, "styles": [ { "name": "default", "label": "Default", "isDefault": true }, @@ -50,6 +50,31 @@ To register a new block type using metadata that can be shared between codebase } ``` +The same file is also used when [submitting block to Block Directory](/docs/getting-started/tutorials/create-block/submitting-to-block-directory.md). + +## Server-side registration + +There is also [`register_block_type_from_metadata`](https://developer.wordpress.org/reference/functions/register_block_type_from_metadata/) function that aims to simplify the block type registration on the server from metadata stored in the `block.json` file. + +This function takes two params: + +- `$path` (`string`) – path to the folder where the `block.json` file is located or full path to the metadata file if named differently. +- `$args` (`array`) – an optional array of block type arguments. Default value: `[]`. Any arguments may be defined. However, the one described below is supported by default: + - `$render_callback` (`callable`) – callback used to render blocks of this block type. + +It returns the registered block type (`WP_Block_Type`) on success or `false` on failure. + +**Example:** + +```php +register_block_type_from_metadata( + __DIR__ . '/notice', + array( + 'render_callback' => 'render_block_core_notice', + ) +); +``` + ## Block API This section describes all the properties that can be added to the `block.json` file to define the behavior and metadata of block types. @@ -105,7 +130,7 @@ The core provided categories are: - widgets - embed -Plugins and Themes can also register [custom block categories](/docs/designers-developers/developers/filters/block-filters.md#managing-block-categories). +Plugins and Themes can also register [custom block categories](/docs/reference-guides/filters/block-filters.md#managing-block-categories). An implementation should expect and tolerate unknown categories, providing some reasonable fallback behavior (e.g. a "text" category). @@ -207,7 +232,7 @@ The [gettext](https://www.gnu.org/software/gettext/) text domain of the plugin/b Attributes provide the structured data needs of a block. They can exist in different forms when they are serialized, but they are declared together under a common interface. -See the [the attributes documentation](/docs/designers-developers/developers/block-api/block-attributes.md) for more details. +See the [the attributes documentation](/docs/reference-guides/block-api/block-attributes.md) for more details. ### Provides Context @@ -219,7 +244,7 @@ See the [the attributes documentation](/docs/designers-developers/developers/blo Context provided for available access by descendants of blocks of this type, in the form of an object which maps a context name to one of the block's own attribute. -See [the block context documentation](/docs/designers-developers/developers/block-api/block-context.md) for more details. +See [the block context documentation](/docs/reference-guides/block-api/block-context.md) for more details. ```json { @@ -239,7 +264,7 @@ See [the block context documentation](/docs/designers-developers/developers/bloc Array of the names of context values to inherit from an ancestor provider. -See [the block context documentation](/docs/designers-developers/developers/block-api/block-context.md) for more details. +See [the block context documentation](/docs/reference-guides/block-api/block-context.md) for more details. ```json { @@ -255,7 +280,7 @@ See [the block context documentation](/docs/designers-developers/developers/bloc - Property: `supports` - Default: `{}` -It contains as set of options to control features used in the editor. See the [the supports documentation](/docs/designers-developers/developers/block-api/block-supports.md) for more details. +It contains as set of options to control features used in the editor. See the [the supports documentation](/docs/reference-guides/block-api/block-supports.md) for more details. ### Style Variations @@ -276,7 +301,7 @@ It contains as set of options to control features used in the editor. See the [t Block styles can be used to provide alternative styles to block. It works by adding a class name to the block's wrapper. Using CSS, a theme developer can target the class name for the style variation if it is selected. -Plugins and Themes can also register [custom block style](/docs/designers-developers/developers/filters/block-filters.md#block-style-variations) for existing blocks. +Plugins and Themes can also register [custom block style](/docs/reference-guides/filters/block-filters.md#block-style-variations) for existing blocks. ### Example @@ -297,7 +322,7 @@ Plugins and Themes can also register [custom block style](/docs/designers-develo It provides structured example data for the block. This data is used to construct a preview for the block to be shown in the Inspector Help Panel when the user mouses over the block. -See the [the example documentation](/docs/designers-developers/developers/block-api/block-registration.md#example-optional) for more details. +See the [the example documentation](/docs/reference-guides/block-api/block-registration.md#example-optional) for more details. ### Editor Script @@ -370,8 +395,6 @@ In `block.json`: } ``` -#### WordPress context - In the context of WordPress, when a block is registered with PHP, it will automatically register all scripts and styles that are found in the `block.json` file and use file paths rather than asset handles. That's why, the `WPDefinedAsset` type has to offer a way to mirror also the shape of params necessary to register scripts and styles using [`wp_register_script`](https://developer.wordpress.org/reference/functions/wp_register_script/) and [`wp_register_style`](https://developer.wordpress.org/reference/functions/wp_register_style/), and then assign these as handles associated with your block using the `script`, `style`, `editor_script`, and `editor_style` block type registration settings. @@ -412,11 +435,9 @@ return array( ); ``` -## Internationalization (not implemented) - -Localized properties will be automatically wrapped in `_x` function calls on the backend and the frontend of WordPress. These translations are added as an inline script to the `wp-block-library` script handle in WordPress core or to the plugin's script handle when it defines metadata definition. +## Internationalization -WordPress string discovery automatically will translate these strings using the `textdomain` property specified in the `block.json` file. +WordPress string discovery automatically will translate fields marked in the documentation as translatable using the `textdomain` property when specified in the `block.json` file. In that case, localized properties will be automatically wrapped in `_x` function calls on the backend of WordPress when executing `register_block_type_from_metadata`. These translations are added as an inline script to the `wp-block-library` script handle in WordPress core or to the plugin's script handle. **Example:** @@ -429,21 +450,7 @@ WordPress string discovery automatically will translate these strings using the } ``` -In JavaScript, with the help of a new helper function `registerBlockTypeFromMetadata`, this becomes: - -```js -const metadata = { - title: _x( 'My block', 'block title', 'my-plugin' ), - description: _x( - 'My block is fantastic', - 'block description', - 'my-plugin' - ), - keywords: [ _x( 'fantastic', 'block keywords', 'my-plugin' ) ], -}; -``` - -In PHP, it is transformed at runtime with a new helper function `register_block_from_metadata` to code roughly equivalent to: +The way `register_block_type_from_metadata` processes translatable values is roughly equivalent to: ```php 'render_block_core_shortcode', - ) -); -``` +Implementation follows the existing [get_plugin_data](https://codex.wordpress.org/Function_Reference/get_plugin_data) function which parses the plugin contents to retrieve the plugin’s metadata, and it applies translations dynamically. ## Backward Compatibility @@ -487,10 +471,10 @@ Once all details are ready, Core Blocks will be migrated iteratively and third-p The following properties are going to be supported for backward compatibility reasons on the client-side only. Some of them might be replaced with alternative APIs in the future: -- `edit` - see the [Edit and Save](/docs/designers-developers/developers/block-api/block-edit-save.md) documentation for more details. -- `save` - see the [Edit and Save](/docs/designers-developers/developers/block-api/block-edit-save.md) documentation for more details. -- `transforms` - see the [Transforms](/docs/designers-developers/developers/block-api/block-registration.md#transforms-optional) documentation for more details. -- `deprecated` - see the [Deprecated Blocks](/docs/designers-developers/developers/block-api/block-deprecation.md) documentation for more details. +- `edit` - see the [Edit and Save](/docs/reference-guides/block-api/block-edit-save.md) documentation for more details. +- `save` - see the [Edit and Save](/docs/reference-guides/block-api/block-edit-save.md) documentation for more details. +- `transforms` - see the [Transforms](/docs/reference-guides/block-api/block-registration.md#transforms-optional) documentation for more details. +- `deprecated` - see the [Deprecated Blocks](/docs/reference-guides/block-api/block-deprecation.md) documentation for more details. - `merge` - undocumented as of today. Its role is to handle merging multiple blocks into one. - `getEditWrapperProps` - undocumented as well. Its role is to inject additional props to the block edit's component wrapper. @@ -510,4 +494,4 @@ wp.blocks.registerBlockType( 'my-block/name', { } ); ``` -In the case of [dynamic blocks](/docs/designers-developers/developers/tutorials/block-tutorial/creating-dynamic-blocks.md) supported by WordPress, it should be still possible to register `render_callback` property using both [`register_block_type`](https://developer.wordpress.org/reference/functions/register_block_type/) and `register_block_type_from_metadata` functions on the server. +In the case of [dynamic blocks](/docs/how-to-guides/block-tutorial/creating-dynamic-blocks.md) supported by WordPress, it should be still possible to register `render_callback` property using both [`register_block_type`](https://developer.wordpress.org/reference/functions/register_block_type/) and `register_block_type_from_metadata` functions on the server. diff --git a/docs/designers-developers/developers/block-api/block-patterns.md b/docs/reference-guides/block-api/block-patterns.md similarity index 100% rename from docs/designers-developers/developers/block-api/block-patterns.md rename to docs/reference-guides/block-api/block-patterns.md diff --git a/docs/designers-developers/developers/block-api/block-registration.md b/docs/reference-guides/block-api/block-registration.md similarity index 67% rename from docs/designers-developers/developers/block-api/block-registration.md rename to docs/reference-guides/block-api/block-registration.md index ffe0981510eb16..5ac9d2a3e78bb3 100644 --- a/docs/designers-developers/developers/block-api/block-registration.md +++ b/docs/reference-guides/block-api/block-registration.md @@ -56,9 +56,9 @@ Blocks are grouped into categories to help users browse and discover them. The core provided categories are: -- common -- formatting -- layout +- text +- media +- design - widgets - embed @@ -67,7 +67,7 @@ The core provided categories are: category: 'widgets', ``` -Plugins and Themes can also register [custom block categories](/docs/designers-developers/developers/filters/block-filters.md#managing-block-categories). +Plugins and Themes can also register [custom block categories](/docs/reference-guides/filters/block-filters.md#managing-block-categories). #### icon (optional) @@ -138,7 +138,7 @@ styles: [ ], ``` -Plugins and Themes can also register [custom block style](/docs/designers-developers/developers/filters/block-filters.md#block-style-variations) for existing blocks. +Plugins and Themes can also register [custom block style](/docs/reference-guides/filters/block-filters.md#block-style-variations) for existing blocks. #### attributes (optional) @@ -166,7 +166,7 @@ attributes: { }, ``` -- **See: [Attributes](/docs/designers-developers/developers/block-api/block-attributes.md).** +- **See: [Attributes](/docs/reference-guides/block-api/block-attributes.md).** #### example (optional) @@ -224,86 +224,27 @@ example: { - **Type:** `Object[]` -Similarly to how the block's style variations can be declared, a block type can define block variations that the user can pick from. The difference is that, rather than changing only the visual appearance, this field provides a way to apply initial custom attributes and inner blocks at the time when a block is inserted. +Similarly to how the block's style variations can be declared, a block type can define block variations that the user can pick from. The difference is that, rather than changing only the visual appearance, this field provides a way to apply initial custom attributes and inner blocks at the time when a block is inserted. See the [Block Variations API](/docs/reference-guides/block-api/block-variations.md) for more details. -By default, all variations will show up in the Inserter in addition to the regular block type item. However, setting the `isDefault` flag for any of the variations listed will override the regular block type in the Inserter. -```js -variations: [ - { - name: 'wordpress', - isDefault: true, - title: __( 'WordPress' ), - description: __( 'Code is poetry!' ), - icon: WordPressIcon, - attributes: { service: 'wordpress' }, - }, - { - name: 'google', - title: __( 'Google' ), - icon: GoogleIcon, - attributes: { service: 'google' }, - }, - { - name: 'twitter', - title: __( 'Twitter' ), - icon: TwitterIcon, - attributes: { service: 'twitter' }, - keywords: [ __('tweet') ], - }, -], -``` - -An object describing a variation defined for the block type can contain the following fields: - -- `name` (type `string`) – The unique and machine-readable name. -- `title` (type `string`) – A human-readable variation title. -- `description` (optional, type `string`) – A detailed variation description. -- `icon` (optional, type `string` | `Object`) – An icon helping to visualize the variation. It can have the same shape as the block type. -- `isDefault` (optional, type `boolean`) – Indicates whether the current variation is the default one. Defaults to `false`. -- `attributes` (optional, type `Object`) – Values that override block attributes. -- `innerBlocks` (optional, type `Array[]`) – Initial configuration of nested blocks. -- `example` (optional, type `Object`) – Example provides structured data for the block preview. You can set to `undefined` to disable the preview shown for the block type. -- `scope` (optional, type `WPBlockVariationScope[]`) - the list of scopes where the variation is applicable. When not provided, it defaults to `block` and `inserter`. Available options: - - `inserter` - Block Variation is shown on the inserter. - - `block` - Used by blocks to filter specific block variations. Mostly used in Placeholder patterns like `Columns` block. - - `transform` - Block Variation will be shown in the component for Block Variations transformations. -- `keywords` (optional, type `string[]`) - An array of terms (which can be translated) that help users discover the variation while searching. -- `isActive` (optional, type `Function`) - A function that accepts a block's attributes and the variation's attributes and determines if a variation is active. This function doesn't try to find a match dynamically based on all block's attributes, as in many cases some attributes are irrelevant. An example would be for `embed` block where we only care about `providerNameSlug` attribute's value. - -It's also possible to override the default block style variation using the `className` attribute when defining block variations. - -```js -variations: [ - { - name: 'blue', - title: __( 'Blue Quote' ), - isDefault: true, - attributes: { color: 'blue', className: 'is-style-blue-quote' }, - icon: 'format-quote', - isActive: ( blockAttributes, variationAttributes ) => - blockAttributes.color === variationAttributes.color - }, -], -``` #### supports (optional) - **_Type:_** `Object` -Supports contains as set of options to control features used in the editor. See the [the supports documentation](/docs/designers-developers/developers/block-api/block-supports.md) for more details. +Supports contains as set of options to control features used in the editor. See the [the supports documentation](/docs/reference-guides/block-api/block-supports.md) for more details. #### transforms (optional) - **Type:** `Object` -Transforms provide rules for what a block can be transformed from and what it can be transformed to. A block can be transformed from another block, a shortcode, a regular expression, a file or a raw DOM node. Take a look at the [Block Transforms API](/docs/designers-developers/developers/block-api/block-transforms.md) for more info about each available transformation. +Transforms provide rules for what a block can be transformed from and what it can be transformed to. A block can be transformed from another block, a shortcode, a regular expression, a file or a raw DOM node. Take a look at the [Block Transforms API](/docs/reference-guides/block-api/block-transforms.md) for more info about each available transformation. #### parent (optional) - **Type:** `Array` -Blocks are able to be inserted into blocks that use [`InnerBlocks`](https://github.com/WordPress/gutenberg/blob/master/packages/block-editor/src/components/inner-blocks/README.md) as nested content. Sometimes it is useful to restrict a block so that it is only available as a nested block. For example, you might want to allow an 'Add to Cart' block to only be available within a 'Product' block. +Blocks are able to be inserted into blocks that use [`InnerBlocks`](https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/inner-blocks/README.md) as nested content. Sometimes it is useful to restrict a block so that it is only available as a nested block. For example, you might want to allow an 'Add to Cart' block to only be available within a 'Product' block. Setting `parent` lets a block require that it is only available when nested within the specified blocks. diff --git a/docs/designers-developers/developers/block-api/block-supports.md b/docs/reference-guides/block-api/block-supports.md similarity index 92% rename from docs/designers-developers/developers/block-api/block-supports.md rename to docs/reference-guides/block-api/block-supports.md index b4d8634ed33816..5b01f69086bfa1 100644 --- a/docs/designers-developers/developers/block-api/block-supports.md +++ b/docs/reference-guides/block-api/block-supports.md @@ -57,7 +57,7 @@ attributes: { - Type: `boolean` - Default value: `true` -This property allows to enable [wide alignment](/docs/designers-developers/developers/themes/theme-support.md#wide-alignment) for your theme. To disable this behavior for a single block, set this flag to `false`. +This property allows to enable [wide alignment](/docs/how-to-guides/themes/theme-support.md#wide-alignment) for your theme. To disable this behavior for a single block, set this flag to `false`. ```js supports: { @@ -86,7 +86,7 @@ supports: { - Default value: null - Subproperties: - `background`: type `boolean`, default value `true` - - `gradient`: type `boolean`, default value `false` + - `gradients`: type `boolean`, default value `false` - `text`: type `boolean`, default value `true` This value signals that a block supports some of the CSS style properties related to color. When it does, the block editor will show UI controls for the user to set their values. @@ -98,7 +98,7 @@ Note that the `text` and `background` keys have a default value of `true`, so if ```js supports: { color: { // This also enables text and background UI controls. - gradient: true // Enable gradients UI control. + gradients: true // Enable gradients UI control. } } ``` @@ -109,7 +109,7 @@ It's possible to disable them individually: supports: { color: { // Text UI control is enabled. background: false, // Disable background UI control. - gradient: true // Enable gradients UI control. + gradients: true // Enable gradients UI control. } } ``` @@ -144,7 +144,7 @@ attributes: { } ``` -- When `gradient` support is declared: it'll be added a new `gradient` attribute of type `string` with no default assigned. It stores the preset values set by the user. The block can apply a default text color by specifying its own attribute with a default e.g.: +- When `gradients` support is declared: it'll be added a new `gradient` attribute of type `string` with no default assigned. It stores the preset values set by the user. The block can apply a default text color by specifying its own attribute with a default e.g.: ```js attributes: { @@ -271,7 +271,7 @@ supports: { - Type: `boolean` - Default value: `false` -This value signals that a block supports the line-height CSS style property. When it does, the block editor will show an UI control for the user to set its value if [the theme declares support](/docs/designers-developers/developers/themes/theme-support.md#supporting-custom-line-heights). +This value signals that a block supports the line-height CSS style property. When it does, the block editor will show an UI control for the user to set its value if [the theme declares support](/docs/how-to-guides/themes/theme-support.md#supporting-custom-line-heights). ```js supports: { @@ -330,7 +330,7 @@ supports: { - Subproperties: - `padding`: type `boolean`, default value `false` -This value signals that a block supports some of the CSS style properties related to spacing. When it does, the block editor will show UI controls for the user to set their values, if [the theme declares support](/docs/designers-developers/developers/themes/theme-support.md##cover-block-padding). +This value signals that a block supports some of the CSS style properties related to spacing. When it does, the block editor will show UI controls for the user to set their values, if [the theme declares support](/docs/how-to-guides/themes/theme-support.md##cover-block-padding). ```js supports: { diff --git a/docs/designers-developers/developers/block-api/block-templates.md b/docs/reference-guides/block-api/block-templates.md similarity index 84% rename from docs/designers-developers/developers/block-api/block-templates.md rename to docs/reference-guides/block-api/block-templates.md index ad961e8f8066d1..d64e80028bc0b2 100644 --- a/docs/designers-developers/developers/block-api/block-templates.md +++ b/docs/reference-guides/block-api/block-templates.md @@ -1,6 +1,6 @@ # Templates -A block template is defined as a list of block items. Such blocks can have predefined attributes, placeholder content, and be static or dynamic. Block templates allow to specify a default initial state for an editor session. +A block template is defined as a list of block items. Such blocks can have predefined attributes, placeholder content, and be static or dynamic. Block templates allow specifying a default initial state for an editor session. The scope of templates include: @@ -32,7 +32,7 @@ function myplugin_register_template() { add_action( 'init', 'myplugin_register_template' ); ``` -The following example in JavaScript creates a new block using [InnerBlocks](https://github.com/WordPress/gutenberg/blob/master/packages/block-editor/src/components/inner-blocks/README.md) and templates, when inserted creates a set of blocks based off the template. +The following example in JavaScript creates a new block using [InnerBlocks](https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/inner-blocks/README.md) and templates, when inserted creates a set of blocks based off the template. ```js const el = wp.element.createElement; @@ -59,7 +59,7 @@ registerBlockType( 'myplugin/template', { }); ``` -See the [Meta Block Tutorial](/docs/designers-developers/developers/tutorials/metabox/meta-block-5-finishing.md) for a full example of a template in use. +See the [Meta Block Tutorial](/docs/how-to-guides/metabox/meta-block-5-finishing.md) for a full example of a template in use. ## Custom Post types @@ -110,6 +110,8 @@ add_action( 'init', 'myplugin_register_template' ); - `all` — prevents all operations. It is not possible to insert new blocks, move existing blocks, or delete blocks. - `insert` — prevents inserting or removing blocks, but allows moving existing blocks. +Lock settings can be inherited by InnerBlocks. If `templateLock` is not set in an InnerBlocks area, the locking of the parent InnerBlocks area is used. If the block is a top level block, the locking configuration of the current post type is used. + ## Nested Templates Container blocks like the columns blocks also support templates. This is achieved by assigning a nested template to the block. diff --git a/docs/designers-developers/developers/block-api/block-transforms.md b/docs/reference-guides/block-api/block-transforms.md similarity index 99% rename from docs/designers-developers/developers/block-api/block-transforms.md rename to docs/reference-guides/block-api/block-transforms.md index ad4f7fcc903477..0be77a7c4f52c6 100644 --- a/docs/designers-developers/developers/block-api/block-transforms.md +++ b/docs/reference-guides/block-api/block-transforms.md @@ -39,7 +39,7 @@ A transformation of type `block` is an object that takes the following parameter - **blocks** _(array)_: a list of known block types. It also accepts the wildcard value (`"*"`), meaning that the transform is available to _all_ block types (eg: all blocks can transform into `core/group`). - **transform** _(function)_: a callback that receives the attributes and inner blocks of the block being processed. It should return a block object or an array of block objects. - **isMatch** _(function, optional)_: a callback that receives the block attributes and should return a boolean. Returning `false` from this function will prevent the transform from being available and displayed as an option to the user. -- **isMultiblock** _(boolean, optional)_: whether the transformation can be applied when multiple blocks are selected. If true, the `transform` function's first parameter will be an array containing each selected block's attributes, and the second an array of each selected block's inner blocks. False by default. +- **isMultiBlock** _(boolean, optional)_: whether the transformation can be applied when multiple blocks are selected. If true, the `transform` function's first parameter will be an array containing each selected block's attributes, and the second an array of each selected block's inner blocks. False by default. - **priority** _(number, optional)_: controls the priority with which a transformation is applied, where a lower value will take precedence over higher values. This behaves much like a [WordPress hook](https://codex.wordpress.org/Plugin_API#Hook_to_WordPress). Like hooks, the default priority is `10` when not otherwise set. **Example: from Paragraph block to Heading block** diff --git a/docs/reference-guides/block-api/block-variations.md b/docs/reference-guides/block-api/block-variations.md new file mode 100644 index 00000000000000..b7b82140dedf9a --- /dev/null +++ b/docs/reference-guides/block-api/block-variations.md @@ -0,0 +1,94 @@ +# Block Variations + +Block Variations is the API that allows a block to have similar versions of it, but all these versions share some common functionality. Each block variation is differentiated from the others by setting some initial attributes or inner blocks. Then at the time when a block is inserted these attributes and/or inner blocks are applied. + +A great way to understand this API better is by using the `embed` block as an example. The numerous existing variations for embed (WordPress, Youtube, etc..) share the same functionality for editing, saving, and so on, but their basic difference is the `providerNameSlug` attribute's value, which defines the provider that needs to be used. + +By default, all variations will show up in the Inserter in addition to the regular block type item. However, setting the `isDefault` flag for any of the variations listed will override the regular block type in the Inserter. + +```js +variations: [ + { + name: 'wordpress', + isDefault: true, + title: __( 'WordPress' ), + description: __( 'Code is poetry!' ), + icon: WordPressIcon, + attributes: { providerNameSlug: 'wordpress' }, + }, + { + name: 'google', + title: __( 'Google' ), + icon: GoogleIcon, + attributes: { providerNameSlug: 'google' }, + }, + { + name: 'twitter', + title: __( 'Twitter' ), + icon: TwitterIcon, + attributes: { providerNameSlug: 'twitter' }, + keywords: [ __('tweet') ], + }, +], +``` + +An object describing a variation defined for the block type can contain the following fields: + +- `name` (type `string`) – The unique and machine-readable name. +- `title` (type `string`) – A human-readable variation title. +- `description` (optional, type `string`) – A detailed variation description. +- `category` (optional, type `string`) - A category classification, used in search interfaces to arrange block types by category. +- `icon` (optional, type `string` | `Object`) – An icon helping to visualize the variation. It can have the same shape as the block type. +- `isDefault` (optional, type `boolean`) – Indicates whether the current variation is the default one. Defaults to `false`. +- `attributes` (optional, type `Object`) – Values that override block attributes. +- `innerBlocks` (optional, type `Array[]`) – Initial configuration of nested blocks. +- `example` (optional, type `Object`) – Example provides structured data for the block preview. You can set to `undefined` to disable the preview shown for the block type. +- `scope` (optional, type `WPBlockVariationScope[]`) - the list of scopes where the variation is applicable. When not provided, it defaults to `block` and `inserter`. Available options: + - `inserter` - Block Variation is shown on the inserter. + - `block` - Used by blocks to filter specific block variations. Mostly used in Placeholder patterns like `Columns` block. + - `transform` - Block Variation will be shown in the component for Block Variations transformations. +- `keywords` (optional, type `string[]`) - An array of terms (which can be translated) that help users discover the variation while searching. +- `isActive` (optional, type `Function`) - A function that accepts a block's attributes and the variation's attributes and determines if a variation is active. This function doesn't try to find a match dynamically based on all block's attributes, as in many cases some attributes are irrelevant. An example would be for `embed` block where we only care about `providerNameSlug` attribute's value. + +The main difference between style variations and block variations is that a style variation just applies a `css class` to the block, so it can be styled in an alternative way. If we want to apply initial attributes or inner blocks, we fall in block variation territory. + +It's also possible to override the default block style variation using the `className` attribute when defining block variations. + +```js +variations: [ + { + name: 'blue', + title: __( 'Blue Quote' ), + isDefault: true, + attributes: { color: 'blue', className: 'is-style-blue-quote' }, + icon: 'format-quote', + isActive: ( blockAttributes, variationAttributes ) => + blockAttributes.color === variationAttributes.color + }, +], +``` + +It's worth mentioning that setting the `isActive` property can be useful for cases you want to use information from the block variation, after a block's creation. For example, this API is used in `useBlockDisplayInformation` hook to fetch and display proper information on places like the `BlockCard` or `Breadcrumbs` components. + + +Block variations can be declared during a block's registration by providing the `variations` key with a proper array of variations, as defined above. In addition, there are ways to register and unregister a `block variation` for a block, after its registration. + +To add a block variation use `wp.blocks.registerBlockVariation()`. + +_Example:_ + +```js +wp.blocks.registerBlockVariation( 'core/embed', { + name: 'custom', + attributes: { providerNameSlug: 'custom' } +} ); +``` + + +To remove a block variation use `wp.blocks.unregisterBlockVariation()`. + +_Example:_ + +```js +wp.blocks.unregisterBlockVariation( 'core/embed', 'youtube' ); +``` diff --git a/docs/designers-developers/developers/block-api/versions.md b/docs/reference-guides/block-api/versions.md similarity index 100% rename from docs/designers-developers/developers/block-api/versions.md rename to docs/reference-guides/block-api/versions.md diff --git a/docs/reference-guides/data/README.md b/docs/reference-guides/data/README.md new file mode 100644 index 00000000000000..d03590a09dcc85 --- /dev/null +++ b/docs/reference-guides/data/README.md @@ -0,0 +1,11 @@ +# Data Module Reference + + - [**core**: WordPress Core Data](/docs/reference-guides/data/data-core.md) + - [**core/annotations**: Annotations](/docs/reference-guides/data/data-core-annotations.md) + - [**core/blocks**: Block Types Data](/docs/reference-guides/data/data-core-blocks.md) + - [**core/block-editor**: The Block Editor’s Data](/docs/reference-guides/data/data-core-block-editor.md) + - [**core/editor**: The Post Editor’s Data](/docs/reference-guides/data/data-core-editor.md) + - [**core/edit-post**: The Editor’s UI Data](/docs/reference-guides/data/data-core-edit-post.md) + - [**core/notices**: Notices Data](/docs/reference-guides/data/data-core-notices.md) + - [**core/nux**: The NUX (New User Experience) Data](/docs/reference-guides/data/data-core-nux.md) + - [**core/viewport**: The Viewport Data](/docs/reference-guides/data/data-core-viewport.md) \ No newline at end of file diff --git a/docs/designers-developers/developers/data/data-core-annotations.md b/docs/reference-guides/data/data-core-annotations.md similarity index 100% rename from docs/designers-developers/developers/data/data-core-annotations.md rename to docs/reference-guides/data/data-core-annotations.md diff --git a/docs/designers-developers/developers/data/data-core-block-editor.md b/docs/reference-guides/data/data-core-block-editor.md similarity index 95% rename from docs/designers-developers/developers/data/data-core-block-editor.md rename to docs/reference-guides/data/data-core-block-editor.md index ded41c1a63dfc6..f7bd0bc226c674 100644 --- a/docs/designers-developers/developers/data/data-core-block-editor.md +++ b/docs/reference-guides/data/data-core-block-editor.md @@ -115,7 +115,7 @@ _Parameters_ _Returns_ -- `?Object`: Block attributes. +- `Object?`: Block attributes. # **getBlockCount** @@ -259,7 +259,7 @@ _Parameters_ - _state_ `Object`: Editor state. - _clientId_ `string`: Block from which to find root client ID. -- _blockName_ `(string|Array)`: Block name(s) to filter. +- _blockName_ `string|string[]`: Block name(s) to filter. - _ascending_ `boolean`: Order results from bottom to top (true) or top to bottom (false). _Returns_ @@ -300,7 +300,7 @@ _Parameters_ _Returns_ -- `Array`: Post blocks. +- `Object[]`: Post blocks. # **getBlocksByClientId** @@ -310,11 +310,11 @@ objects. _Parameters_ - _state_ `Object`: Editor state. -- _clientIds_ `Array`: Client IDs for which blocks are to be returned. +- _clientIds_ `string[]`: Client IDs for which blocks are to be returned. _Returns_ -- `Array`: Block objects. +- `WPBlock[]`: Block objects. # **getBlockSelectionEnd** @@ -363,7 +363,7 @@ _Parameters_ _Returns_ -- `Array`: Items that appear in inserter. +- `WPEditorTransformItem[]`: Items that appear in inserter. _Type Definition_ @@ -417,7 +417,7 @@ _Parameters_ _Returns_ -- `Array`: Array of dragged block client ids. +- `string[]`: Array of dragged block client ids. # **getFirstMultiSelectedBlockClientId** @@ -466,7 +466,7 @@ _Parameters_ _Returns_ -- `Array`: Items that appear in inserter. +- `WPEditorInserterItem[]`: Items that appear in inserter. _Type Definition_ @@ -480,7 +480,7 @@ _Properties_ - _title_ `string`: Title of the item, as it appears in the inserter. - _icon_ `string`: Dashicon for the item, as it appears in the inserter. - _category_ `string`: Block category that the item is associated with. -- _keywords_ `Array`: Keywords that can be searched to find this item. +- _keywords_ `string[]`: Keywords that can be searched to find this item. - _isDisabled_ `boolean`: Whether or not the user should be prevented from inserting this item. - _frecency_ `number`: Heuristic that combines frequency and recency. @@ -657,6 +657,7 @@ _Returns_ Returns the initial caret position for the selected block. This position is to used to position the caret properly when the selected block changes. +If the current block is not a RichText, having initial position set to 0 means "focus block" _Parameters_ @@ -664,7 +665,7 @@ _Parameters_ _Returns_ -- `?Object`: Selected block. +- `0|-1|null`: Initial position. # **getSelectionEnd** @@ -1059,7 +1060,7 @@ Generator that triggers an action used to duplicate a list of blocks. _Parameters_ -- _clientIds_ `Array`: +- _clientIds_ `string[]`: - _updateSelection_ `boolean`: # **enterFormattedText** @@ -1134,10 +1135,11 @@ be inserted, optionally at a specific index respective a root block list. _Parameters_ -- _blocks_ `Array`: Block objects to insert. +- _blocks_ `Object[]`: Block objects to insert. - _index_ `?number`: Index at which block should be inserted. - _rootClientId_ `?string`: Optional root client ID of block list on which to insert. - _updateSelection_ `?boolean`: If true block selection will be updated. If false, block selection will not change. Defaults to true. +- _initialPosition_ `0|-1|null`: Initial focus position. Setting it to null prevent focusing the inserted block. - _meta_ `?Object`: Optional Meta values to be passed to the action object. _Returns_ @@ -1217,7 +1219,7 @@ replacing. _Parameters_ -- _blocks_ `Array`: Array of block objects. +- _blocks_ `Object[]`: Array of block objects. _Returns_ @@ -1244,7 +1246,7 @@ the set of specified client IDs are to be removed. _Parameters_ -- _clientIds_ `(string|Array)`: Client IDs of blocks to remove. +- _clientIds_ `string|string[]`: Client IDs of blocks to remove. - _selectPrevious_ `boolean`: True if the previous block should be selected when a block is removed. # **replaceBlock** @@ -1254,8 +1256,8 @@ with one or more replacement blocks. _Parameters_ -- _clientId_ `(string|Array)`: Block client ID to replace. -- _block_ `(Object|Array)`: Replacement block(s). +- _clientId_ `(string|string[])`: Block client ID to replace. +- _block_ `(Object|Object[])`: Replacement block(s). _Returns_ @@ -1268,10 +1270,10 @@ one or more replacement blocks. _Parameters_ -- _clientIds_ `(string|Array)`: Block client ID(s) to replace. -- _blocks_ `(Object|Array)`: Replacement block(s). +- _clientIds_ `(string|string[])`: Block client ID(s) to replace. +- _blocks_ `(Object|Object[])`: Replacement block(s). - _indexToSelect_ `number`: Index of replacement block to select. -- _initialPosition_ `number`: Index of caret after in the selected block after the operation. +- _initialPosition_ `0|-1|null`: Index of caret after in the selected block after the operation. - _meta_ `?Object`: Optional Meta values to be passed to the action object. # **replaceInnerBlocks** @@ -1282,8 +1284,9 @@ specified client ID should be replaced. _Parameters_ - _rootClientId_ `string`: Client ID of the block whose InnerBlocks will re replaced. -- _blocks_ `Array`: Block objects to insert as new InnerBlocks +- _blocks_ `Object[]`: Block objects to insert as new InnerBlocks - _updateSelection_ `?boolean`: If true block selection will be updated. If false, block selection will not change. Defaults to false. +- _initialPosition_ `0|-1|null`: Initial block position. _Returns_ @@ -1308,6 +1311,7 @@ _Parameters_ - _selectionStart_ `WPBlockSelection`: The selection start. - _selectionEnd_ `WPBlockSelection`: The selection end. +- _initialPosition_ `0|-1|null`: Initial block position. _Returns_ @@ -1323,7 +1327,7 @@ reflects a reverse selection. _Parameters_ - _clientId_ `string`: Block client ID. -- _initialPosition_ `?number`: Optional initial position. Pass as -1 to reflect reverse selection. +- _initialPosition_ `0|-1|null`: Optional initial position. Pass as -1 to reflect reverse selection. _Returns_ @@ -1369,7 +1373,7 @@ Generator that triggers an action used to enable or disable the block moving mod _Parameters_ -- _hasBlockMovingClientId_ `(string|null)`: Enable/Disable block moving mode. +- _hasBlockMovingClientId_ `string|null`: Enable/Disable block moving mode. # **setHasControlledInnerBlocks** @@ -1421,7 +1425,7 @@ Returns an action object used in signalling that the user has begun to drag bloc _Parameters_ -- _clientIds_ `Array`: An array of client ids being dragged +- _clientIds_ `string[]`: An array of client ids being dragged _Returns_ @@ -1530,8 +1534,9 @@ attributes with the specified client IDs have been updated. _Parameters_ -- _clientIds_ `(string|Array)`: Block client IDs. -- _attributes_ `Object`: Block attributes to be merged. +- _clientIds_ `string|string[]`: Block client IDs. +- _attributes_ `Object`: Block attributes to be merged. Should be keyed by clientIds if uniqueByBlock is true. +- _uniqueByBlock_ `boolean`: true if each block in clientIds array has a unique set of attributes _Returns_ diff --git a/docs/designers-developers/developers/data/data-core-blocks.md b/docs/reference-guides/data/data-core-blocks.md similarity index 91% rename from docs/designers-developers/developers/data/data-core-blocks.md rename to docs/reference-guides/data/data-core-blocks.md index 655c4f0d7a3390..2e8c236bbf13a9 100644 --- a/docs/designers-developers/developers/data/data-core-blocks.md +++ b/docs/reference-guides/data/data-core-blocks.md @@ -17,7 +17,7 @@ _Parameters_ _Returns_ -- `?Array`: Block Styles. +- `Array?`: Block Styles. # **getBlockSupport** @@ -45,7 +45,7 @@ _Parameters_ _Returns_ -- `?Object`: Block Type. +- `Object?`: Block Type. # **getBlockTypes** @@ -71,7 +71,7 @@ _Parameters_ _Returns_ -- `(Array|void)`: Block variations. +- `(WPBlockVariation[]|void)`: Block variations. # **getCategories** @@ -83,7 +83,7 @@ _Parameters_ _Returns_ -- `Array`: Categories list. +- `WPBlockCategory[]`: Categories list. # **getChildBlockNames** @@ -120,7 +120,7 @@ _Parameters_ _Returns_ -- `?string`: Default block name. +- `string?`: Default block name. # **getDefaultBlockVariation** @@ -149,7 +149,7 @@ _Parameters_ _Returns_ -- `?string`: Name of the block for handling non-block content. +- `string?`: Name of the block for handling non-block content. # **getGroupingBlockName** @@ -161,7 +161,7 @@ _Parameters_ _Returns_ -- `?string`: Name of the block for handling unregistered blocks. +- `string?`: Name of the block for handling unregistered blocks. # **getUnregisteredFallbackBlockName** @@ -173,7 +173,7 @@ _Parameters_ _Returns_ -- `?string`: Name of the block for handling unregistered blocks. +- `string?`: Name of the block for handling unregistered blocks. # **hasBlockSupport** @@ -229,7 +229,7 @@ _Parameters_ _Returns_ -- `Array`: Whether block type matches search term. +- `Object[]`: Whether block type matches search term. @@ -258,7 +258,7 @@ Returns an action object used in signalling that new block styles have been adde _Parameters_ - _blockName_ `string`: Block name. -- _styles_ `(Array|Object)`: Block styles. +- _styles_ `Array|Object`: Block styles. _Returns_ @@ -270,7 +270,7 @@ Returns an action object used in signalling that block types have been added. _Parameters_ -- _blockTypes_ `(Array|Object)`: Block types received. +- _blockTypes_ `Array|Object`: Block types received. _Returns_ @@ -283,7 +283,7 @@ Returns an action object used in signalling that new block variations have been _Parameters_ - _blockName_ `string`: Block name. -- _variations_ `(WPBlockVariation|Array)`: Block variations. +- _variations_ `WPBlockVariation|WPBlockVariation[]`: Block variations. _Returns_ @@ -308,7 +308,7 @@ Returns an action object used in signalling that block styles have been removed. _Parameters_ - _blockName_ `string`: Block name. -- _styleNames_ `(Array|string)`: Block style names. +- _styleNames_ `Array|string`: Block style names. _Returns_ @@ -320,7 +320,7 @@ Returns an action object used to remove a registered block type. _Parameters_ -- _names_ `(string|Array)`: Block name. +- _names_ `string|Array`: Block name. _Returns_ @@ -333,7 +333,7 @@ Returns an action object used in signalling that block variations have been remo _Parameters_ - _blockName_ `string`: Block name. -- _variationNames_ `(string|Array)`: Block variation names. +- _variationNames_ `string|string[]`: Block variation names. _Returns_ @@ -345,7 +345,7 @@ Returns an action object used to set block categories. _Parameters_ -- _categories_ `Array`: Block categories. +- _categories_ `Object[]`: Block categories. _Returns_ diff --git a/docs/designers-developers/developers/data/data-core-edit-post.md b/docs/reference-guides/data/data-core-edit-post.md similarity index 98% rename from docs/designers-developers/developers/data/data-core-edit-post.md rename to docs/reference-guides/data/data-core-edit-post.md index ddaac2ac0ca707..63e1f1ba6b69f0 100644 --- a/docs/designers-developers/developers/data/data-core-edit-post.md +++ b/docs/reference-guides/data/data-core-edit-post.md @@ -35,7 +35,7 @@ _Parameters_ _Returns_ -- `Array`: Active meta box locations. +- `string[]`: Active meta box locations. # **getAllMetaBoxes** @@ -325,7 +325,7 @@ name(s) should be hidden. _Parameters_ -- _blockNames_ `Array`: Names of block types to hide. +- _blockNames_ `string[]`: Names of block types to hide. _Returns_ @@ -424,7 +424,7 @@ name(s) should be shown. _Parameters_ -- _blockNames_ `Array`: Names of block types to show. +- _blockNames_ `string[]`: Names of block types to show. _Returns_ diff --git a/docs/designers-developers/developers/data/data-core-editor.md b/docs/reference-guides/data/data-core-editor.md similarity index 98% rename from docs/designers-developers/developers/data/data-core-editor.md rename to docs/reference-guides/data/data-core-editor.md index 621461421e085c..4fbce4a3c1b932 100644 --- a/docs/designers-developers/developers/data/data-core-editor.md +++ b/docs/reference-guides/data/data-core-editor.md @@ -203,7 +203,7 @@ _Parameters_ _Returns_ -- `Array`: Filtered set of blocks for save. +- `WPBlock[]`: Filtered set of blocks for save. # **getClientIdsOfDescendants** @@ -331,7 +331,7 @@ _Parameters_ _Returns_ -- `?string`: Preview Link. +- `string?`: Preview Link. # **getEditedPostSlug** @@ -373,8 +373,22 @@ _Returns_ - `Array`: Block list. +# **getEditorSelection** + +Returns the current selection. + +_Parameters_ + +- _state_ `Object`: + +_Returns_ + +- `WPBlockSelection`: The selection end. + # **getEditorSelectionEnd** +> **Deprecated** since Gutenberg 10.0.0. + Returns the current selection end. _Parameters_ @@ -387,6 +401,8 @@ _Returns_ # **getEditorSelectionStart** +> **Deprecated** since Gutenberg 10.0.0. + Returns the current selection start. _Parameters_ @@ -780,7 +796,7 @@ Return true if the current post has already been published. _Parameters_ - _state_ `Object`: Global application state. -- _currentPost_ `?Object`: Explicit current post for bypassing registry selector. +- _currentPost_ `Object?`: Explicit current post for bypassing registry selector. _Returns_ @@ -1061,7 +1077,7 @@ Storage). _Parameters_ -- _options_ `?Object`: Extra flags to identify the autosave. +- _options_ `Object?`: Extra flags to identify the autosave. # **clearSelectedBlock** @@ -1347,7 +1363,7 @@ _Parameters_ - _post_ `Object`: Post object. - _edits_ `Object`: Initial edited attributes object. -- _template_ `?Array`: Block Template. +- _template_ `Array?`: Block Template. # **setupEditorState** diff --git a/docs/designers-developers/developers/data/data-core-keyboard-shortcuts.md b/docs/reference-guides/data/data-core-keyboard-shortcuts.md similarity index 88% rename from docs/designers-developers/developers/data/data-core-keyboard-shortcuts.md rename to docs/reference-guides/data/data-core-keyboard-shortcuts.md index fefa8e189e2150..9211b1c4808370 100644 --- a/docs/designers-developers/developers/data/data-core-keyboard-shortcuts.md +++ b/docs/reference-guides/data/data-core-keyboard-shortcuts.md @@ -17,7 +17,7 @@ _Parameters_ _Returns_ -- `Array`: Shortcuts. +- `string[]`: Shortcuts. # **getCategoryShortcuts** @@ -30,7 +30,7 @@ _Parameters_ _Returns_ -- `Array`: Shortcut names. +- `string[]`: Shortcut names. # **getShortcutAliases** @@ -43,7 +43,7 @@ _Parameters_ _Returns_ -- `Array`: Key combinations. +- `WPShortcutKeyCombination[]`: Key combinations. # **getShortcutDescription** @@ -56,7 +56,7 @@ _Parameters_ _Returns_ -- `?string`: Shortcut description. +- `string?`: Shortcut description. # **getShortcutKeyCombination** @@ -69,7 +69,7 @@ _Parameters_ _Returns_ -- `?WPShortcutKeyCombination`: Key combination. +- `WPShortcutKeyCombination?`: Key combination. # **getShortcutRepresentation** @@ -79,11 +79,11 @@ _Parameters_ - _state_ `Object`: Global state. - _name_ `string`: Shortcut name. -- _representation_ (unknown type): Type of representation (display, raw, ariaLabel). +- _representation_ `keyof FORMATTING_METHODS`: Type of representation (display, raw, ariaLabel). _Returns_ -- `?string`: Shortcut representation. +- `string?`: Shortcut representation. diff --git a/docs/designers-developers/developers/data/data-core-notices.md b/docs/reference-guides/data/data-core-notices.md similarity index 98% rename from docs/designers-developers/developers/data/data-core-notices.md rename to docs/reference-guides/data/data-core-notices.md index 0ecaa5cc3a7a19..87066f5e0f4c37 100644 --- a/docs/designers-developers/developers/data/data-core-notices.md +++ b/docs/reference-guides/data/data-core-notices.md @@ -18,7 +18,7 @@ _Parameters_ _Returns_ -- `Array`: Array of notices. +- `WPNotice[]`: Array of notices. diff --git a/docs/designers-developers/developers/data/data-core-nux.md b/docs/reference-guides/data/data-core-nux.md similarity index 97% rename from docs/designers-developers/developers/data/data-core-nux.md rename to docs/reference-guides/data/data-core-nux.md index ad0a93e2bde235..2abad5d1f52775 100644 --- a/docs/designers-developers/developers/data/data-core-nux.md +++ b/docs/reference-guides/data/data-core-nux.md @@ -90,7 +90,7 @@ the user through a series of tips step by step. _Parameters_ -- _tipIds_ `Array`: Which tips to show in the guide. +- _tipIds_ `string[]`: Which tips to show in the guide. _Returns_ diff --git a/docs/designers-developers/developers/data/data-core-viewport.md b/docs/reference-guides/data/data-core-viewport.md similarity index 100% rename from docs/designers-developers/developers/data/data-core-viewport.md rename to docs/reference-guides/data/data-core-viewport.md diff --git a/docs/designers-developers/developers/data/data-core.md b/docs/reference-guides/data/data-core.md similarity index 93% rename from docs/designers-developers/developers/data/data-core.md rename to docs/reference-guides/data/data-core.md index 37c4ad7d5f8584..4f9f16e4eab8a9 100644 --- a/docs/designers-developers/developers/data/data-core.md +++ b/docs/reference-guides/data/data-core.md @@ -21,11 +21,11 @@ _Parameters_ - _state_ `Object`: Data state. - _action_ `string`: Action to check. One of: 'create', 'read', 'update', 'delete'. - _resource_ `string`: REST resource to check, e.g. 'media' or 'posts'. -- _id_ `[string]`: Optional ID of the rest resource to check. +- _id_ `string=`: Optional ID of the rest resource to check. _Returns_ -- `(boolean|undefined)`: Whether or not the user can perform the action, or `undefined` if the OPTIONS request is still being made. +- `boolean|undefined`: Whether or not the user can perform the action, or `undefined` if the OPTIONS request is still being made. # **getAuthors** @@ -34,7 +34,7 @@ Returns all available authors. _Parameters_ - _state_ `Object`: Data state. -- _query_ `(Object|undefined)`: Optional object of query parameters to include with request. +- _query_ `Object|undefined`: Optional object of query parameters to include with request. _Returns_ @@ -109,7 +109,7 @@ _Parameters_ _Returns_ -- `?Object`: The entity record, merged with its edits. +- `Object?`: The entity record, merged with its edits. # **getEmbedPreview** @@ -167,7 +167,7 @@ _Parameters_ _Returns_ -- `?Object`: Record. +- `Object?`: Record. # **getEntityRecordEdits** @@ -182,7 +182,7 @@ _Parameters_ _Returns_ -- `?Object`: The entity record's edits. +- `Object?`: The entity record's edits. # **getEntityRecordNonTransientEdits** @@ -201,7 +201,7 @@ _Parameters_ _Returns_ -- `?Object`: The entity record's non transient edits. +- `Object?`: The entity record's non transient edits. # **getEntityRecords** @@ -231,7 +231,7 @@ _Parameters_ _Returns_ -- `?Object`: The entity record's save error. +- `Object?`: The entity record's save error. # **getLastEntitySaveError** @@ -246,7 +246,7 @@ _Parameters_ _Returns_ -- `?Object`: The entity record's save error. +- `Object?`: The entity record's save error. # **getRawEntityRecord** @@ -262,7 +262,7 @@ _Parameters_ _Returns_ -- `?Object`: Object with the entity's raw attributes. +- `Object?`: Object with the entity's raw attributes. # **getRedoEdit** @@ -275,7 +275,7 @@ _Parameters_ _Returns_ -- `?Object`: The edit. +- `Object?`: The edit. # **getReferenceByDistinctEdits** @@ -321,7 +321,7 @@ _Parameters_ _Returns_ -- `?Object`: The edit. +- `Object?`: The edit. # **getUserQueryResults** @@ -531,6 +531,8 @@ _Parameters_ - _name_ `string`: Name of the deleted entity. - _recordId_ `string`: Record ID of the deleted entity. - _query_ `?Object`: Special query parameters for the DELETE API call. +- _options_ `[Object]`: Delete options. +- _options.\_\_unstableFetch_ `[Function]`: Internal use only. Function to call instead of `apiFetch()`. Must return a control descriptor. # **editEntityRecord** @@ -558,7 +560,7 @@ post have been received. _Parameters_ - _postId_ `number`: The id of the post that is parent to the autosave. -- _autosaves_ `(Array|Object)`: An array of autosaves or singular autosave object. +- _autosaves_ `Array|Object`: An array of autosaves or singular autosave object. _Returns_ @@ -610,9 +612,10 @@ _Parameters_ - _kind_ `string`: Kind of the received entity. - _name_ `string`: Name of the received entity. -- _records_ `(Array|Object)`: Records received. +- _records_ `Array|Object`: Records received. - _query_ `?Object`: Query Object. -- _invalidateCache_ `?boolean`: Should invalidate query caches +- _invalidateCache_ `?boolean`: Should invalidate query caches. +- _edits_ `?Object`: Edits to reset. _Returns_ @@ -663,7 +666,7 @@ Returns an action object used in signalling that authors have been received. _Parameters_ - _queryID_ `string`: Query ID. -- _users_ `(Array|Object)`: Users received. +- _users_ `Array|Object`: Users received. _Returns_ @@ -696,6 +699,7 @@ _Parameters_ - _record_ `Object`: Record to be saved. - _options_ `Object`: Saving options. - _options.isAutosave_ `[boolean]`: Whether this is an autosave. +- _options.\_\_unstableFetch_ `[Function]`: Internal use only. Function to call instead of `apiFetch()`. Must return a control descriptor. # **undo** diff --git a/docs/designers-developers/developers/filters/README.md b/docs/reference-guides/filters/README.md similarity index 100% rename from docs/designers-developers/developers/filters/README.md rename to docs/reference-guides/filters/README.md diff --git a/docs/designers-developers/developers/filters/autocomplete-filters.md b/docs/reference-guides/filters/autocomplete-filters.md similarity index 100% rename from docs/designers-developers/developers/filters/autocomplete-filters.md rename to docs/reference-guides/filters/autocomplete-filters.md diff --git a/docs/designers-developers/developers/filters/block-filters.md b/docs/reference-guides/filters/block-filters.md similarity index 91% rename from docs/designers-developers/developers/filters/block-filters.md rename to docs/reference-guides/filters/block-filters.md index 81e4fd9d1a91a7..963f7937734c16 100644 --- a/docs/designers-developers/developers/filters/block-filters.md +++ b/docs/reference-guides/filters/block-filters.md @@ -4,7 +4,7 @@ To modify the behavior of existing blocks, WordPress exposes several APIs: ### Block Style Variations -Block Style Variations allow providing alternative styles to existing blocks. They work by adding a className to the block's wrapper. This className can be used to provide an alternative styling for the block if the style variation is selected. See the [Getting Started with JavaScript tutorial](/docs/designers-developers/developers/tutorials/javascript/) for a full example. +Block Style Variations allow providing alternative styles to existing blocks. They work by adding a className to the block's wrapper. This className can be used to provide an alternative styling for the block if the style variation is selected. See the [Getting Started with JavaScript tutorial](/docs/how-to-guides/javascript/) for a full example. _Example:_ @@ -178,7 +178,7 @@ wp.hooks.addFilter( ); ``` -_Note:_ A [block validation](/docs/designers-developers/developers/block-api/block-edit-save.md#validation) error will occur if this filter modifies existing content the next time the post is edited. The editor verifies that the content stored in the post matches the content output by the `save()` function. +_Note:_ A [block validation](/docs/reference-guides/block-api/block-edit-save.md#validation) error will occur if this filter modifies existing content the next time the post is edited. The editor verifies that the content stored in the post matches the content output by the `save()` function. To avoid this validation error, use `render_block` server-side to modify existing post content instead of this filter. See [render_block documentation](https://developer.wordpress.org/reference/hooks/render_block/). @@ -319,6 +319,30 @@ wp.hooks.addFilter( 'editor.BlockListBlock', 'my-plugin/with-client-id-class-nam ``` {% end %} +#### `media.crossOrigin` + +Used to set or modify the `crossOrigin` attribute for foreign-origin media elements (i.e ``, `