forked from WordPress/block-development-examples
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
README.md for _bin and workflows folder + removed unnecesary scripts …
…in package.json + general .cursorrules
- Loading branch information
1 parent
9101d87
commit b941315
Showing
7 changed files
with
160 additions
and
144 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,5 @@ | ||
| IMPORTANT: Document changes on each step in a `CHANGELOG.md` file. | ||
|
|
||
| - Create a new minor version on each session and add the current date beside that version | ||
| - Add patches version on each new set of changes added to `CHANGELOG.md` | ||
| - Place newer changes (and latest versions) first in `CHANGELOG.md` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,72 @@ | ||
| # GitHub Workflows | ||
|
|
||
| This directory contains GitHub Actions workflows that automate various tasks in the repository. Below is an overview of each workflow: | ||
|
|
||
| ## Main Workflows | ||
|
|
||
| ### 🚀 Zips on Deploy Branch (`main.yml`) | ||
|
|
||
| Handles the deployment process when changes are pushed to the trunk branch: | ||
|
|
||
| - Merges trunk branch into deploy branch | ||
| - Installs dependencies | ||
| - Runs deployment tasks | ||
| - Commits and pushes changes to deploy branch | ||
|
|
||
| ### 🔍 Static Linting (`pull-request-actions.yml`) | ||
|
|
||
| Runs linting checks on pull requests and trunk branch pushes: | ||
|
|
||
| - PHP file linting | ||
| - JavaScript file linting | ||
| - CSS file linting | ||
| - Runs on Node.js 18 and latest LTS versions | ||
|
|
||
| ## Data Management Workflows | ||
|
|
||
| ### 👥 Update GitHub Contributors (`github-contributors.yml`) | ||
|
|
||
| Updates the list of project contributors: | ||
|
|
||
| - Fetches contributor information | ||
| - Updates `_data/examples.json` | ||
| - Can be manually triggered | ||
|
|
||
| ### 📊 Contributor Details (`contributor-details.yml`) | ||
|
|
||
| Maintains detailed contributor information: | ||
|
|
||
| - Fetches detailed contributor data | ||
| - Updates `_data/contributors.json` | ||
| - Can be manually triggered | ||
|
|
||
| ### 📅 Update Creation and Modification Dates (`update-dates.yml`) | ||
|
|
||
| Maintains file metadata: | ||
|
|
||
| - Updates creation and modification dates | ||
| - Updates `_data/examples.json` | ||
| - Runs monthly and can be manually triggered | ||
|
|
||
| ## Scripts | ||
|
|
||
| The `scripts/` directory contains shell scripts used by these workflows: | ||
|
|
||
| - `fetch_contributors.sh`: Fetches basic contributor information | ||
| - `fetch_contributor_details.sh`: Retrieves detailed contributor data | ||
| - `update_dates.sh`: Updates file timestamps | ||
|
|
||
| ## Permissions | ||
|
|
||
| Most workflows require write permissions to: | ||
|
|
||
| - Push changes to branches | ||
| - Update JSON data files | ||
| - Commit changes | ||
|
|
||
| ## Triggers | ||
|
|
||
| - `main.yml`: Triggered on push to trunk branch | ||
| - `pull-request-actions.yml`: Triggered on pull requests and trunk pushes | ||
| - `update-dates.yml`: Runs monthly and manual trigger | ||
| - Others: Can be manually triggered via workflow_dispatch |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -106,4 +106,3 @@ _app/build | |
|
|
||
| *.code-workspace | ||
| _app/src/data | ||
| .cursorrules | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,146 +1,63 @@ | ||
| # Block Development Examples - Build Scripts | ||
| # \_bin Directory Scripts | ||
|
|
||
| This folder contains utility scripts for managing WordPress block development examples. These scripts help automate various tasks like creating new examples, updating documentation, and managing the codebase. | ||
| This directory contains utility scripts used for managing and maintaining the Block Development Examples project. | ||
|
|
||
| ## Directory Structure | ||
| ## Available Scripts | ||
|
|
||
| ``` | ||
| _bin/ | ||
| ├── copyGutenbergExample/ # Scripts for copying/creating new examples | ||
| ├── utils/ # Shared utility functions | ||
| ├── _addExamplesPerTagReadme.js | ||
| ├── constants.js | ||
| ├── prepareDataForApp.js | ||
| └── updateTableMarkdown.js | ||
| ``` | ||
| You can run these scripts using the npm/pnpm commands defined in the root `package.json`: | ||
|
|
||
| ## Available Scripts | ||
| ### Table Generation | ||
|
|
||
| ### Creating Examples | ||
| ### Updating Documentation | ||
|
|
||
| ```bash | ||
| # Create a new example by copying an existing one | ||
| npm run create-example:copy | ||
| - `npm run table:update` - Generates the main examples table in the root README.md | ||
| - `npm run table:update [example-slug]` - Update README table for a specific example | ||
| - `npm run table:update:all` - Updates all tables in the project documentation | ||
|
|
||
| # Create a brand new example from template | ||
| npm run create-example:new | ||
| ``` | ||
| ### Contributors Management | ||
|
|
||
| The `create-example:copy` script launches an interactive CLI that: | ||
| 1. Prompts you to select a source example | ||
| 2. Asks for a new example name | ||
| 3. Generates a unique ID | ||
| 4. Lets you select tags | ||
| 5. Creates the new example with customized files | ||
| - `npm run contributors:update` - Updates the contributors information in documentation | ||
|
|
||
| ### Updating Documentation | ||
| ### Date Management | ||
|
|
||
| ```bash | ||
| # Update README table for a specific example | ||
| npm run table:update [example-slug] | ||
| - `npm run dates:update` - Updates dates across the project files | ||
|
|
||
| # Update all README tables | ||
| npm run table:update:all | ||
| ``` | ||
| ## Script Files Structure | ||
|
|
||
| ### Utility Scripts | ||
| The scripts are organized in the following structure: | ||
|
|
||
| ```bash | ||
| # Generate a random hex code (used for example IDs) | ||
| npm run get:hexcode | ||
| ``` | ||
| . | ||
| ├── CHANGELOG.md | ||
| ├── README.md | ||
| ├── src | ||
| │ ├── constants.ts | ||
| │ ├── index.ts | ||
| │ ├── services | ||
| │ │ ├── DatesService.ts | ||
| │ │ └── tableMarkdown.ts | ||
| │ ├── types | ||
| │ │ ├── config.ts | ||
| │ │ ├── errors.ts | ||
| │ │ └── example.ts | ||
| │ └── utils | ||
| │ ├── compose.ts | ||
| │ ├── errors.ts | ||
| │ ├── fileOperations.ts | ||
| │ ├── logging.ts | ||
| │ └── validation.ts | ||
| └── tsconfig.json | ||
| ``` | ||
|
|
||
| ## Development | ||
|
|
||
| The scripts are written in TypeScript and use various utilities to manage project documentation and metadata. To modify or extend these scripts: | ||
|
|
||
| 1. Navigate to the appropriate file in the `src` directory | ||
| 2. Make your changes | ||
| 3. Run `pnpm build` to compile if necessary | ||
| 4. Test your changes using the corresponding npm script | ||
|
|
||
| ## Note | ||
|
|
||
| ## Core Files Explained | ||
|
|
||
| ### copyGutenbergExample/ | ||
| - `index.js` - Main entry point for example creation wizard | ||
| - `initCreateExample.js` - Handles the example creation process | ||
| - `customizeBlockJson.js` - Updates block.json for new examples | ||
| - `customizePackageJson.js` - Updates package.json for new examples | ||
| - `addExamplesJson.js` - Adds new example to examples.json registry | ||
| - `duplicateExampleNewName.js` - Handles folder duplication | ||
|
|
||
| ### utils/ | ||
| - `generateExamplesTableMarkdown.js` - Generates markdown tables for documentation | ||
| - `log.js` - Consistent logging utilities with color support | ||
| - `randomHexCode.js` - Generates unique example IDs | ||
|
|
||
| ### Root Files | ||
| - `constants.js` - Shared configuration and constants | ||
| - `prepareDataForApp.js` - Processes data for the web application | ||
| - `updateTableMarkdown.js` - Updates README.md tables | ||
| - `_addExamplesPerTagReadme.js` - Manages tag-based documentation | ||
|
|
||
| ## Key Features | ||
|
|
||
| 1. **Example Management** | ||
| - Create new examples from existing ones | ||
| - Generate unique IDs for examples | ||
| - Customize block and package configurations | ||
| - Update documentation automatically | ||
|
|
||
| 2. **Documentation** | ||
| - Auto-generate markdown tables | ||
| - Maintain tag-based organization | ||
| - Keep README files in sync | ||
|
|
||
| 3. **Development Tools** | ||
| - Random ID generation | ||
| - Consistent logging | ||
| - File operation utilities | ||
|
|
||
| ## File Operations | ||
|
|
||
| The scripts handle several types of files: | ||
| - `block.json` - Block configuration | ||
| - `package.json` - Package configuration | ||
| - `examples.json` - Example registry | ||
| - `README.md` - Documentation files | ||
|
|
||
| ## Data Structure | ||
|
|
||
| Examples are organized with: | ||
| - Unique slug/ID combinations | ||
| - Associated tags | ||
| - Descriptions | ||
| - Related files and configurations | ||
|
|
||
| ## Best Practices | ||
|
|
||
| 1. Always use the provided scripts for: | ||
| - Creating new examples | ||
| - Updating documentation | ||
| - Managing configurations | ||
|
|
||
| 2. Maintain consistent formatting: | ||
| - Use provided logging utilities | ||
| - Follow existing naming conventions | ||
| - Keep documentation up-to-date | ||
|
|
||
| 3. Error Handling: | ||
| - Scripts include basic error handling | ||
| - Check console output for issues | ||
| - Verify file operations completed successfully | ||
|
|
||
| ## Dependencies | ||
|
|
||
| Key dependencies used by these scripts: | ||
| - `@inquirer/prompts` - Interactive CLI | ||
| - `chalk` - Console styling | ||
| - `execa` - Process execution | ||
| - `fs-extra` - Enhanced file operations | ||
| - `markdown-table` - Table generation | ||
| - `replace-in-file` - File content updates | ||
|
|
||
| ## Contributing | ||
|
|
||
| When modifying these scripts: | ||
| 1. Maintain TypeScript-style type safety | ||
| 2. Follow functional programming patterns | ||
| 3. Update documentation as needed | ||
| 4. Test thoroughly before committing | ||
|
|
||
| ## Related Documentation | ||
|
|
||
| - [Block Development Examples Wiki](https://github.com/WordPress/block-development-examples/wiki) | ||
| - [WordPress Block Development](https://developer.wordpress.org/block-editor/) | ||
| These scripts are essential for maintaining project consistency and automating routine tasks. Always run them from the root directory of the project. |
Oops, something went wrong.