diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4281f095..7bdc6e7a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,65 +1,76 @@ -# Contributing to this project +# Contributing to this Project -Hi! Thank you for your interest in contributing to this project, we really appreciate it. +Hello! Thank you for your interest in contributing to this project. We appreciate every bit of help, whether it’s through reporting bugs, suggesting new features, fixing issues, or submitting pull requests. -There are many ways to contribute – reporting bugs, feature suggestions, fixing bugs, submitting pull requests for enhancements. +## How You Can Contribute -## Reporting Bugs, Asking Questions, Sending Suggestions +### Reporting Bugs, Asking Questions, Making Suggestions -Just [file a GitHub issue](./issues/new), that’s all! If you want to prefix the title with a “Question:”, “Bug:”, or the general area of the issue, that would be helpful, but by no means mandatory. If you have write access, add the appropriate labels. +For any of these, simply [open a GitHub issue](../../issues/new). If you’d like, prefix the title with “Question:”, “Bug:”, or a relevant area, but this isn’t mandatory. Adding appropriate labels can also be helpful if you have write access. -If you’re filing a bug, specific steps to reproduce are helpful. Please include the URL of the page that has the bug, along with what you expected to see and what happened instead. +When reporting a bug, please include: +- Clear steps to reproduce the issue. +- The URL where the issue appears (if applicable). +- What you expected to see and what actually happened. -## Setting up the dev environment +### Setting Up the Development Environment -If you want to contribute code to the project you have to set up the environment locally. Make sure that you have `node`, `npm`, `docker` and `webpack` installed. +To contribute code, you’ll need to set up the environment locally. Make sure you have `node`, `npm`, `docker`, and `webpack` installed. -The working directories are the `theme` & `plugin` directories. If you change something in another location of the repository the pull request will be ignored. +The **`theme`** and **`plugin`** directories contain the working files where code changes should be made. Pull requests with changes outside these directories will not be accepted. -The development server and all dependencies are handled by [@wordpress/env](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-env/). Make sure you have [docker installed](https://docs.docker.com/compose/install/) and run `npm start` in the directory. Your spawned WordPress instance will be available under `http://localhost` with the account `admin:password`. +This project’s development server and dependencies are managed by [@wordpress/env](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-env/). Here’s how to get started: -Please be aware, that you should usually not write code directly on the main branch. +1. Ensure [Docker is installed](https://docs.docker.com/compose/install/). +2. Run `npm start` from the project’s root directory to initialize the WordPress environment. You’ll find the WordPress instance at `http://localhost` with the credentials `admin:password`. +3. Start the live reloading watcher by running `npm run watch`. This ensures that any changes you make are compiled automatically, and [LiveReload](http://livereload.com/extensions/) refreshes your browser. -Start the watcher with the terminal command `npm run watch`. Webpack will make sure that the code will be compiled and that your browser gets a [LiveReload](http://livereload.com/extensions/) command. +Before committing any changes, run `npm run test` to make sure your code adheres to the coding standards and passes all tests. -Before committing execute the command `npm run test` to test if your code follows the general coding standards. +> **Note**: Please work in a branch rather than directly on the main branch. -This project uses the `@wordpress\env` package to provide the development server. Please refer to the [`wp-env`-documentation](https://github.com/WordPress/gutenberg/tree/master/packages/env) for more details. +For more details, see the [`wp-env` documentation](https://github.com/WordPress/gutenberg/tree/master/packages/env). -## I'm stuck, what do I do? +## Need Help? -Not knowing what to do is perfectly normal for any developer or programmer. One of the main skills of a good programmer is the ability to quickly adapt patterns and find solutions. In short: Being able type the right question into Google. If you are stuck somewhere in project development we suggest the following: +It’s normal to get stuck! Here are some resources to help you move forward: -1. Check out the [WordPress Codex](https://codex.wordpress.org) and read the documentation of what you're trying to build. -2. Look at how others do it. Places to look for best practices are the [TwentyNinteen project](https://github.com/WordPress/twentynineteen), the [Underscores project](https://github.com/automattic/_s) or the [TwentySeventeen project](https://github.com/WordPress/twentyseventeen). -3. Ask a senior programmer nearby +1. **WordPress Codex**: Refer to the [WordPress Codex](https://codex.wordpress.org) for detailed documentation. +2. **Reference Projects**: See best practices in action with projects like [TwentyNineteen](https://github.com/WordPress/twentynineteen), [Underscores](https://github.com/automattic/_s), and [TwentySeventeen](https://github.com/WordPress/twentyseventeen). +3. **Ask for Help**: Reach out to a senior developer or mentor for guidance. ## Development Workflow -To keep the work in this repository structured and maintainable, we follow a certain way to add changes and code. A good workflow is structured like this: +To keep contributions organized and maintainable, please follow this workflow: -1. Write or take an issue about the problem you want to solve -2. Add your own branch to the repository and add code to this branch -3. As soon as you have a presentable solution, add a pull request to the master branch -4. Get reviews for your solution and make sure the automated tests pass -5. Before merging the PR to the master branch, update your branch from master to resolve conflicts -6. Merge the PR into the master branch, test the solution and delete your branch +1. Create or choose an existing issue related to your contribution. +2. Create a new branch for your work. +3. Implement your changes. +4. Submit a pull request (PR) to the `main` branch for review. +5. Ensure all automated tests pass and address any feedback. +6. Resolve conflicts by updating your branch from `main`. +7. Once approved, merge the PR, test your changes, and delete your branch. -### Naming branches +### Naming Branches -Ideally name your branches with prefixes and descriptions, like this: [type]/[change]. A good prefix would be: +Use prefixes to describe the type of work being done. Suggested formats are: +- **add/** – for new features. +- **try/** – for experimental or tentative changes. +- **update/** – for enhancements to existing features. +- **fix/** – for bug fixes or addressing unwanted behavior. -* add/ = add a new feature -* try/ = experimental feature, "tentatively add" -* update/ = update an existing feature -* fix/ = fix a bug or unwanted behavior - -For example, add/gallery-block means you're working on adding a new gallery block. +For example, `add/gallery-block` describes a branch where you’re adding a new gallery block. ## Releasing Updates -The release workflow is more or less automated. A github workflow takes the code, runs the tests and builds it into a release-ready zip. This zip is then attached to a GitHub release, from where it is then pushed to our own update server. To create a release refer to the [`Create Release`-Action](./actions/workflows/release.yml), trigger it with the `Run Workflow` button and define the specifics of the new version. +The release process is largely automated. Our GitHub workflow will build the code and package it into a release-ready zip file, which is attached to a GitHub release and distributed via our update server. + +To create a release: +1. Go to the [`Create Release` action](./actions/workflows/release.yml) and trigger it with the `Run Workflow` button. +2. Specify the version details for the new release. + +> **Note**: We follow [Semantic Versioning (SemVer)](https://semver.org/), so please review [npm’s versioning guidelines](https://docs.npmjs.com/cli/v7/commands/npm-version) to choose an appropriate version. -Please refer to the documentation of [npm version](https://docs.npmjs.com/cli/v7/commands/npm-version) to learn more about how to set the version. In determining which version should be the next one we try to follow the SemVer Specification. Read [more about that here](https://semver.org/). +While anyone with write access can initiate a release, it’s recommended that only the *build master* or *project manager* handle this to maintain consistency. -While theoretically everyone with write access to the repository has the ability to push a release, the release should only be done by one person, either the *build master* or the *project manager*. +Thank you for contributing to the project! diff --git a/README.md b/README.md index 72dc0889..2be8f0d4 100644 --- a/README.md +++ b/README.md @@ -1,44 +1,73 @@ # WordPress Project Boilerplate + [![🧪 Tests](../../actions/workflows/test.yml/badge.svg)](../../actions/workflows/test.yml) -There are probably more WordPress boilerplates than actual themes & plugins available for bootstrapping your work on an amazing WordPress project. And that is very much okay, because every developer, every agency has their own little flavors in how they like to do things. +This boilerplate provides a structured project template for creating a **Hybrid WordPress Theme**, which combines traditional classic theme features with the block-based capabilities introduced by the WordPress Block Editor (Gutenberg). Leveraging **@wordpress/env**, **webpack**, and **PostCSS**, this boilerplate adheres to WordPress best practices by separating data and business logic (plugin) from presentation and styling (theme). + +Learn more about Hybrid Themes [here](https://gutenbergmarket.com/news/what-are-hybrid-wordpress-themes). + +## Getting Started + +Follow these steps to set up your project and start coding: + +### Prerequisites + +1. **Use as Repository Template**: Create a new repository from this template to avoid manually setting up the structure. +2. **Project Slug**: Choose a unique slug that won’t conflict with other repositories or projects. + +### Step 1: Set Up Project Slug and Names + +1. **Replace Project Slug**: + - Search and replace (case-sensitive): + - `lhpbp` with your new project-specific slug. + - `LHPBP` with the uppercase version of your slug. + +2. **Update Details**: + - Modify project information in `package.json`. + - Update file headers in `theme/style.css` and `plugin/lhpbpp.php`. + +3. **Rename Plugin File**: + - Rename the main plugin file from `plugin/lhpbpp.php` to `plugin/p.php`. + +### Step 2: Run the Development Environment + +1. **Start the Environment**: + - Run `npm start` to spin up the Docker environment. + +2. **Access WordPress Admin**: + - Open `http://localhost/wp-admin` in your browser. + - Use the credentials `admin` (username) and `password` (password) to log in. + +### Step 3: Test the Release Workflow -That is the reason we made this boilerplate. We liked the work of so many other developers before us, but we never found the perfect boilerplate that fit our style of work. The result is this, a very opinionated project boilerplate based on @wordpress/env, webpack and PostCSS. +1. **Set up GitHub Secrets**: + - Add `GH_ADMIN_TOKEN` to [GitHub Action secrets](../../settings/secrets/actions) and [Dependabot secrets](../../settings/secrets/dependabot). -Included in this boilerplate is the structure needed to release a theme and an acompanying plugin for a WordPress client project. As per WordPress guidlines and best practices, all business and data logic should be put into the plugin, all presentation and styles should be put into the theme. +2. **Create a Test Release**: + - Trigger a patch release via the [GitHub release action](../../actions/workflows/release.yml). -This boilerplate will give you all the tools you need to write, test and publish your WordPress project, either for commercial clients or to publish the theme & plugin in the WordPress.org repository. +3. **Verify Release**: + - Check the [releases](../../releases) section on GitHub to confirm the release was created and uploaded. -## Getting started +### Step 4: Finalize Documentation -These steps will guide you through the setup process up until you can start -writing functions, markup and styles for your project. +1. **Customize Documentation**: + - Edit `project-README.md` with your specific project details. -For the sake of scope we will assume that you know the slug of your project. -Please make sure that the slug is unique to the system of the client, our -projects and the WordPress.org project repository. +2. **Organize README Files**: + - Delete or rename this `README.md` (current file). + - Rename `project-README.md` to `README.md`. -We will also assume, that you have already configured your GitHub repository to -your liking, downloaded the source of the boilerplate and uploaded it to your -new repository. So let's get started: +3. **Celebrate 🎉** -### Project Slug & Names -- [ ] Search & Replace (case sensitive) `lhpbp` with your new WordPress project slug -- [ ] Search & Replace (case sensitive) `LHPBP` with your new WordPress project slug -- [ ] Adjust details in `package.json` and update the file headers in `theme/style.css` and `plugin/lhpbpp.php` -- [ ] Rename the main plugin file from `plugin/lhpbpp.php` to `plugin/p.php` +## What Are Hybrid Themes? -### Running the enviroment -- [ ] Type `npm start` into the terminal to spin up the docker enviroment -- [ ] Open `http://localhost/wp-admin` and log in with `admin:password` +Hybrid WordPress Themes represent a **middle ground** between traditional Classic Themes and Full Site Editing (FSE) Block Themes. They combine elements of both, allowing users to take advantage of block-based design capabilities while retaining familiar classic theme functionality. Hybrid Themes offer a balanced approach, providing flexibility without requiring a full commitment to FSE. -### Test Release -- [ ] Add the `GH_ADMIN_TOKEN` secret to the [action secrets](../../settings/secrets/actions) and [dependabot secrets](../../settings/secrets/dependabot). -- [ ] Create a [patch release](../../actions/workflows/release.yml) with the github action -- [ ] Check if the [release](../../releases) has been created and uploaded in the GitHub release section +**Benefits of Hybrid Themes**: +- **Balanced Editing Experience**: Supports both classic and block editing modes, allowing for flexibility in design and layout. +- **Enhanced Block Capabilities**: Includes features like block templates, block parts, and custom configurations via `theme.json`. +- **Greater Design Control**: Allows extensive customization for pages, posts, and archive layouts while keeping traditional editing options. +- **Compatibility**: Works seamlessly with both classic WordPress setups and Block Editor elements, providing the best of both worlds. -### Finishing touches -- [ ] Edit the `project-README.md` with the appropriate text about your theme -- [ ] Delete (or rename) the `README.md` (this file) -- [ ] Rename the `project-README.md` to `README.md` -- [ ] 🎉 Celebrate! +This boilerplate enables you to develop a flexible, scalable Hybrid Theme that leverages the strengths of both classic and block-based features, delivering a future-ready WordPress experience with maximal control and compatibility. diff --git a/project-README.md b/project-README.md index f656e733..77644767 100644 --- a/project-README.md +++ b/project-README.md @@ -6,14 +6,43 @@ This WordPress project is made with love and brought to you by the folks of [WP Munich](http://www.wp-munich.de) and [Luehrsen // Heinrich](http://www.luehrsen-heinrich.de). +## What's in This Project? + +This project includes two main components: + +1. **Hybrid Theme**: A flexible WordPress theme that combines traditional theme features with block-based capabilities, offering compatibility with both the classic editor and the Full Site Editing (FSE) experience. This hybrid approach allows for advanced customization while retaining a familiar editing environment. All styling for custom blocks is stored in the theme, keeping presentation elements within the theme layer. + +2. **Plugin for Business Logic**: A companion plugin that encapsulates all business logic, data handling, and custom functionality, ensuring that essential features remain intact even if the theme is changed. Additionally, custom block logic is stored within the plugin, enabling reusable and consistent block functionality independent of the theme. + +Together, these components provide a complete WordPress solution that offers both flexibility in design and consistency in functionality. + +## Key Terminal Commands + +Here are some of the most useful commands available in this boilerplate to assist with setup, development, and release. + +### General Commands +- **`npm start`**: Initializes the Docker-based WordPress development environment using `wp-env`. Runs necessary initial scripts defined in `prestart`. +- **`npm run stop`**: Stops the `wp-env` Docker environment without deleting data, useful when you want to pause development. +- **`npm run build`**: Builds the project in development mode using `webpack`. +- **`npm run release`**: Prepares a production-ready release by running all necessary build steps: `release:build`, `release:version`, and `release:package`. + +### Development Workflow +- **`npm run watch`**: Starts `webpack` in watch mode, automatically rebuilding the project when file changes are detected. Ideal for local development alongside `npm start`. +- **`npm run dev`**: Runs both `npm start` and `npm run watch`, setting up the development environment and live rebuilding in one step. + +### Linting & Fixing +- **`npm run lint`**: Runs lint checks on PHP, JavaScript, and CSS files. +### Testing +- **`npm test`**: Runs all unit tests across plugins and themes. + ## Contributing -Every bit of help is highly appreciated. Even if you don't code you can file an issue and help us find bugs or shape new features. Please see the [CONTRIBUTING.md](./CONTRIBUTING.md) on how to contribute. +Every bit of help is highly appreciated. Even if you don't code, you can file an issue to help us find bugs or suggest new features. Please see the [CONTRIBUTING.md](./CONTRIBUTING.md) for details on how to contribute. ## License -This plugin is licensed under [GNU General Public License v2 (or later)](./LICENSE.md). +This plugin is licensed under the [GNU General Public License v2 (or later)](./LICENSE.md). ## Changelog -Please find the current [changelog here](./../../releases). +Please find the current [changelog here](../../releases).