Skip to content

Commit

Permalink
docs: align line lengths and quotes
Browse files Browse the repository at this point in the history
  • Loading branch information
@tyrann0us
tyrann0us committed Sep 5, 2024
1 parent db67323 commit a955768
Show file tree
Hide file tree
Showing 9 changed files with 106 additions and 83 deletions.
4 changes: 2 additions & 2 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,8 @@ With [GitHub Actions](https://github.com/features/actions), you can create custo
software development lifecycle directly in your GitHub repository. These workflows consist of
different tasks, called actions, that can be executed automatically when certain events occur.

At Syde, we use GitHub Actions for a wide range of tasks. From various quality assurance tests
(e.g. static analysis checks, PHPUnit tests, etc.), to asset (pre)compilation
At Syde, we use GitHub Actions for a wide range of tasks. From various quality assurance tests (
e.g., static analysis checks, PHPUnit tests, etc.), to asset (pre)compilation
with [Composer Asset Compiler](https://github.com/inpsyde/composer-asset-compiler), release
generation, deployments (CI/CD), and container registry management: all automatable, recurring tasks
are performed in GitHub Actions.
Expand Down
30 changes: 16 additions & 14 deletions docs/archive-creation.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
# Create plugin archive

This action can be used to create plugin archives in a controlled and isolated environment via GitHub Actions.
This action can be used to create plugin archives in a controlled and isolated environment via
GitHub Actions.

To achieve that, the reusable workflow:

Expand All @@ -11,7 +12,8 @@ To achieve that, the reusable workflow:
5. Executes Rector if configured by the package
6. Re-installs dependencies without dev-dependencies
7. Sets current commit hash and plugin version in the plugin's main file
8. Runs `wp dist-archive` to create the final archive (with builtin support for a `.distignore` file)
8. Runs `wp dist-archive` to create the final archive (with builtin support for a `.distignore`
file)
9. Uploads it as an artifact for download or further processing

## Simple usage example
Expand Down Expand Up @@ -45,24 +47,24 @@ jobs:
|-----------------------|---------------------------------------------------------------|------------------------------------------------------------------------------------------------|
| `NODE_OPTIONS` | `''` | Space-separated list of command-line Node options |
| `NODE_VERSION` | `18` | Node version with which the assets will be compiled |
| `NPM_REGISTRY_DOMAIN` | `"https://npm.pkg.github.com/"` | Domain of the private npm registry |
| `PACKAGE_MANAGER` | `"yarn"` | Package manager with which the dependencies should be installed (`npm` or `yarn`) |
| `COMPOSER_ARGS` | `'--no-dev --no-scripts --prefer-dist --optimize-autoloader'` | Set of arguments passed to Composer when gathering production dependencies |
| `PHP_VERSION` | `"8.0"` | PHP version to use when gathering production dependencies |
| `PHP_VERSION_BUILD` | `"8.0"` | PHP version to use when executing build tools |
| `ARCHIVE_NAME` | `""` | The name of the zip archive (falls back to the repository name) |
| `PLUGIN_MAIN_FILE` | `"index.php"` | The name of the main plugin file |
| `PLUGIN_FOLDER_NAME` | `""` | The name of the plugin folder (falls back to the archive name, if set, or the repository name) |
| `NPM_REGISTRY_DOMAIN` | `'https://npm.pkg.github.com/'` | Domain of the private npm registry |
| `PACKAGE_MANAGER` | `'yarn'` | Package manager with which the dependencies should be installed (`npm` or `yarn`) |
| `COMPOSER_ARGS` | `'--no-dev --no-scripts --prefer-dist --optimize-autoloader'` | Set of arguments passed to Composer when gathering production dependencies |
| `PHP_VERSION` | `'8.0'` | PHP version to use when gathering production dependencies |
| `PHP_VERSION_BUILD` | `'8.0'` | PHP version to use when executing build tools |
| `ARCHIVE_NAME` | `''` | The name of the zip archive (falls back to the repository name) |
| `PLUGIN_MAIN_FILE` | `'index.php'` | The name of the main plugin file |
| `PLUGIN_FOLDER_NAME` | `''` | The name of the plugin folder (falls back to the archive name, if set, or the repository name) |
| `PLUGIN_VERSION` | - | The new plugin version |
| `PRE_SCRIPT` | `""` | Run custom shell code before creating the release archive |
| `PRE_SCRIPT` | `''` | Run custom shell code before creating the release archive |
| `COMPILE_ASSETS_ARGS` | `'-v --env=root'` | Set of arguments passed to Composer Asset Compiler |

#### A note on `PLUGIN_VERSION`

The workflow will accept any arbitrary string and will use it without validation or sanitization.
Adding this would mean reduced flexibility at increased complexity. Adding standardization/validation
is encouraged but should take place in the controlling workflow, where the conventions and requirements
of the project/team/client are known.
Adding this would mean reduced flexibility at increased complexity. Adding
standardization/validation is encouraged but should take place in the controlling workflow, where
the conventions and requirements of the project/team/client are known.

## Secrets

Expand Down
7 changes: 4 additions & 3 deletions docs/assets-compilation.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,8 @@

This workflow utilizes
the [Composer Asset Compiler](https://github.com/inpsyde/composer-asset-compiler) to compile assets.
For details, refer to [Pre-compilation](https://github.com/inpsyde/composer-asset-compiler#pre-compilation).
For details, refer
to [Pre-compilation](https://github.com/inpsyde/composer-asset-compiler#pre-compilation).

**Simplest possible example:**

Expand All @@ -25,8 +26,8 @@ jobs:
| `NODE_OPTIONS` | `''` | Space-separated list of command-line Node options |
| `NODE_VERSION` | `18` | Node version with which the assets will be compiled |
| `NPM_REGISTRY_DOMAIN` | `https://npm.pkg.github.com/` | Domain of the private npm registry |
| `PACKAGE_MANAGER` | `yarn` | Package manager with which the dependencies should be installed (`npm` or `yarn`) |
| `PHP_VERSION` | `"8.0"` | PHP version with which the assets compilation is to be executed |
| `PACKAGE_MANAGER` | `'yarn'` | Package manager with which the dependencies should be installed (`npm` or `yarn`) |
| `PHP_VERSION` | `'8.0'` | PHP version with which the assets compilation is to be executed |
| `COMPOSER_ARGS` | `'--prefer-dist'` | Set of arguments passed to Composer |
| `COMPILE_ASSETS_ARGS` | `'-v --env=root'` | Set of arguments passed to Composer Asset Compiler |

Expand Down
23 changes: 12 additions & 11 deletions docs/automatic-release.md
View file
Original file line number Diff line number Diff line change
@@ -1,29 +1,30 @@
# Automatic release

This workflow utilizes [semantic-release](https://github.com/semantic-release/semantic-release) to create a package
release.
Note that you must stick to
their [commit message convention](https://github.com/semantic-release/semantic-release#commit-message-format) to use it.
This workflow utilizes [semantic-release](https://github.com/semantic-release/semantic-release) to
create a package release. Note that you must stick to
their [commit message convention](https://github.com/semantic-release/semantic-release#commit-message-format)
to use it.

You can provide a `release.config.js` file in your repository to create a custom release that uses the following
semantic-release plugins:
You can provide a `release.config.js` file in your repository to create a custom release that uses
the following semantic-release plugins:

- [git](https://github.com/semantic-release/git)
- [npm](https://github.com/semantic-release/npm)
- [exec](https://github.com/semantic-release/exec)

Otherwise, the workflow will create the release with a [standard set of configurations](../templates/automatic-release/release.config.js), updating the version in the
following files:
Otherwise, the workflow will create the release with
a [standard set of configurations](../templates/automatic-release/release.config.js), updating the
version in the following files:

- `CHANGELOG.md`
- `composer.json`
- `package-lock.json`
- `package.json`
- `style.css` or the main plugin file (automatically discovered by the workflow)

By default, every push to the `main` and `next` branches will release a stable version, and every push to the `alpha`
and `beta` branches will create a pre-release version.
If you want to use a different configuration, please provide your custom `release.config.js` file.
By default, every push to the `main` and `next` branches will release a stable version, and every
push to the `alpha` and `beta` branches will create a pre-release version. If you want to use a
different configuration, please provide your custom `release.config.js` file.

**Simplest possible example:**

Expand Down
51 changes: 30 additions & 21 deletions docs/build-and-push-assets.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,26 +10,29 @@ To achieve that, the reusable workflow:

## Where are assets stored

Two inputs can be used to define branches as assets storage: `BUILT_BRANCH_NAME` and `RELEASE_BRANCH_NAME`.
Two inputs can be used to define branches as assets storage: `BUILT_BRANCH_NAME` and
`RELEASE_BRANCH_NAME`.

`BUILT_BRANCH_NAME` is used only for `branch` events. If defined, compiled assets will be stored in the branch of this
name. For example, if `BUILT_BRANCH_NAME` is set to `${{ github.ref_name }}-built`, when pushing to the `main` branch,
compiled assets will be stored in the `main-built` branch (the branch will be created if it does not exist).
`BUILT_BRANCH_NAME` is used only for `branch` events. If defined, compiled assets will be stored in
the branch of this name. For example, if `BUILT_BRANCH_NAME` is set to
`${{ github.ref_name }}-built`, when pushing to the `main` branch, compiled assets will be stored in
the `main-built` branch (the branch will be created if it does not exist).

`RELEASE_BRANCH_NAME` is only used for tag events. If defined and the tag being pushed points to the latest commit of
the default branch of the GitHub repository, compiled assets will be pushed to the branch of this name, and the tag will
be moved there (the branch will be created if it does not exist).
`RELEASE_BRANCH_NAME` is only used for tag events. If defined and the tag being pushed points to the
latest commit of the default branch of the GitHub repository, compiled assets will be pushed to the
branch of this name, and the tag will be moved there (the branch will be created if it does not
exist).

The main benefit of using `BUILT_BRANCH_NAME` is not to pollute the main development branch
with commits containing compiled assets. With `RELEASE_BRANCH_NAME`, you can gain linear tag history
by always tagging only the latest commit from the main development branch.
The main benefit of using `BUILT_BRANCH_NAME` is not to pollute the main development branch with
commits containing compiled assets. With `RELEASE_BRANCH_NAME`, you can gain linear tag history by
always tagging only the latest commit from the main development branch.

## Build script

In step *2* above, the assets are "built", whatever that means for a package. For maximum
flexibility, the workflow relies on a "script" to be defined in `package.json`. There are two
possible building scripts: a "*dev*" script which is executed on regular pushes to branches, and
a "*prod*" script, which is executed when a tag is pushed.
possible building scripts: a "*dev*" script which is executed on regular pushes to branches, and a "
*prod*" script, which is executed when a tag is pushed.

By default, the two scripts are `encore dev` and `encore prod`, but can be configured
via [inputs](#inputs).
Expand All @@ -41,8 +44,8 @@ is moved** to point to the commit that contains the compiled assets.

## Recommendations for consuming packages

- The consuming packages compiled assets' target folder(s) must be **git-ignored** and marked
as `linguist-generated` in `.gitattributes`.
- The consuming packages compiled assets' target folder(s) must be **git-ignored** and marked as
`linguist-generated` in `.gitattributes`.
- The calling workflows should
use ["concurrency" settings](https://docs.github.com/en/actions/using-jobs/using-concurrency) to
avoid conflicts when a push happens before the current workflow is not completed.
Expand Down Expand Up @@ -88,7 +91,8 @@ jobs:
This is not the simplest possible example, but it showcases all the recommendations.
**Note**: Do not set `cancel-in-progress: true` to the `concurrency` setting because it interrupts the workflow.
**Note**: Do not set `cancel-in-progress: true` to the `concurrency` setting because it interrupts
the workflow.

## Configuration parameters

Expand All @@ -99,7 +103,7 @@ This is not the simplest possible example, but it showcases all the recommendati
| `NODE_OPTIONS` | `''` | Space-separated list of command-line Node options |
| `NODE_VERSION` | `18` | Node version with which the assets will be compiled |
| `NPM_REGISTRY_DOMAIN` | `https://npm.pkg.github.com/` | Domain of the private npm registry |
| `PACKAGE_MANAGER` | `yarn` | Package manager with which the dependencies should be installed (`npm` or `yarn`) |
| `PACKAGE_MANAGER` | `'yarn'` | Package manager with which the dependencies should be installed (`npm` or `yarn`) |
| `WORKING_DIRECTORY` | `'./'` | Working directory path |
| `COMPILE_SCRIPT_PROD` | `'build'` | Script added to `npm run` or `yarn` to build production assets |
| `COMPILE_SCRIPT_DEV` | `'build:dev'` | Script added to `npm run` or `yarn` to build development assets |
Expand Down Expand Up @@ -210,7 +214,8 @@ jobs:

> Can I have multiple output folders for my package? What about files?

Yes, `inputs.ASSETS_TARGET_PATHS` and `inputs.ASSETS_TARGET_FILES` accept multiple space-separated paths for directories and files, respectively.
Yes, `inputs.ASSETS_TARGET_PATHS` and `inputs.ASSETS_TARGET_FILES` accept multiple space-separated
paths for directories and files, respectively.

```yaml
name: Build and push assets
Expand Down Expand Up @@ -268,7 +273,8 @@ hash that triggered the compilation.
As for the "noise", it will indeed be there. However, considering that all workflow commit messages
start with the prefix `[BOT]`, it would be quite easy to ignore them without any cognitive effort.

By defining `BUILT_BRANCH_NAME`, you keep commits containing compiled assets separated in the built branch.
By defining `BUILT_BRANCH_NAME`, you keep commits containing compiled assets separated in the built
branch.

---

Expand Down Expand Up @@ -315,8 +321,10 @@ Please note that in such cases it is a good practice not to use a "personal" Git

For tags, the pushed tag name is always used.

For branches, it depends on the `BUILT_BRANCH_NAME` input value. For example, when `BUILT_BRANCH_NAME`
is `${{ github.ref_name}}-built` and the branch triggering the workflow is `main`, the built branch name will resolve
For branches, it depends on the `BUILT_BRANCH_NAME` input value. For example, when
`BUILT_BRANCH_NAME`
is `${{ github.ref_name}}-built` and the branch triggering the workflow is `main`, the built branch
name will resolve
to `main-built`. In this case, require the `dev-main-built` branch in `composer.json`.

---
Expand All @@ -332,4 +340,5 @@ The logic in the example above will behave like this:
- If `github.ref_name` is equal to `dev-main`, the value of `BUILT_BRANCH_NAME` will be `main`
- If `github.ref_name` is equal to `dev-beta`, the value of `BUILT_BRANCH_NAME` will be `beta`
- If `github.ref_name` is equal to `dev-alpha`, the value of `BUILT_BRANCH_NAME` will be `alpha`
- If none of the above conditions are met, the value of `BUILT_BRANCH_NAME` will be `''`, which is the default
- If none of the above conditions are met, the value of `BUILT_BRANCH_NAME` will be `''`, which is
the default
Loading

0 comments on commit a955768

Please sign in to comment.