Most of our code is available on GitHub. You can find our repositories at the Trew Knowledge GitHub Org or at the WP VIP GitHub Org. In some rare occasions, we might have repositories in other places like GitLab or Bitbucket.When starting a new project there are some things we need to do before we begin working on the code. This includes creating a new repository, adjusting settings and setting up CI/CD.
For WP VIP projects it is all done for us using the VIP Go Skeleton repository as a template.For non-WP VIP projects, we need to it ourselves. Visit TK’s fork of WP VIP Skeleton, click on the “Use this template” button and follow the instructions.
We need to set up the build, test and deploy process. This is usually done using GitHub Actions, but it can also be done using other CI/CD tools like CircleCI.This process differs between WPVIP and non-WPVIP projects.
For WPVIP projects we use their CircleCI account. We need to request VIP to add the project to CircleCI.
The way it works is that CircleCI will do everything we want it to do and in the end it will deploy the final code to another branch suffixed by -built (i.e. main-built). We then need to update the deployment branch through the WordPress VIP dasboard for that specific environment. See more details here.
You can control what goes into the -built branch by adding and modifying a .deployignore file. This file should be added to the root of the project and should contain a list of files and folders that should not be included in the final build. It works the same way as a .gitignore file.Example Scenario:
You want your source code to be in the main branch and the build folder to be ignored. However, you want the build folder to be included in the -built branch and the source folder to be ignored.
For Non-WPVIP projects we use GitHub Actions. This gives us much more flexibility. We need to create at least one new workflow file in the .github/workflows/ folder.Preferrably we should have at least 2. One workflow tracks changes to plugins and deploys only those. The other tracks changes to the theme and only builds and deploys the files it needs to. If you have multiple themes you should consider one workflow for each theme.Deployment is usually done via SSH. We need to add the SSH key and some other secrets to the repository and then use it in the workflow file.
version: 2jobs: build: docker: # Pick a base image which matches the version of Node you need for # building from https://hub.docker.com/r/circleci/node/tags/ # # Note: If using a different container, make sure it contains at least # git 2.6.0. (Use -stretch for circleci/node containers.) - image: cimg/node:18.17.1 branches: # Don't build from a branch with the `-built` suffix, to # prevent endless loops of deploy scripts. # REQUIRED: If you're amended an existing config, the below are two # of the required lines you must add ignore: - /^.*-built$/ only: - main steps: - checkout # Configure TK Blocks plugin build steps - run: name: 'Install npm packages for TK Blocks plugin' command: | cd plugins/tk-blocks npm ci - run: name: 'Build' command: | cd plugins/tk-blocks npm run build # Configure build step for the TK theme - run: name: 'Install npm packages' command: | cd themes/tk npm ci - run: name: 'Build' command: | cd themes/tk npm run build # Test to ensure the build was good, do not deploy bad stuff! - run: name: Test the build command: | if [ -f themes/tk/build/js/main.js ] && [ -f themes/tk/build/css/main.css ]; then echo "Build succeeded"; else echo "Build failed, file missing"; exit 1 fi # Uncomment this and supply your ssh fingerprint to enable CircleCI to push the built branch to GitHub - add_ssh_keys: fingerprints: - "b0:b5:0d:3e:d1:7d:58:fd:08:2f:03:fc:dd:4b:86:c3" # Run the deploy: # REQUIRED: If you're amended an existing config, the below are two # of the required lines you must add # This will push the result to the {currentbranch}-built branch - deploy: name: Deploy -built branch to github command: bash <(curl -s "https://raw.githubusercontent.com/Automattic/vip-go-build/master/deploy.sh")
In order for GitHub Actions to work, you may need to add some secrets to the repository. These secrets are used to authenticate with the server and to deploy the code.
The following are only examples. Make sure you adjust to your situation.
All projects should set the main branch as a protected branch. This means that no one can push directly to the main branch and all changes must be made through a pull request. This is to ensure that all changes are reviewed and tested before they are merged into the main branch.Here are the common rules we follow:
Require a pull request before merging
Require approvals (at least 1).
Dismiss stale pull request approvals when new commits are pushed.
All projects should have a pull request template. This is a file that is automatically added to the pull request when it is created. It should contain a checklist of things that need to be done before the pull request can be merged.
.github/pull_request_template.md
Copy
## Description 📝Please provide a brief summary of the changes and their purpose.## JIRA Ticket(s) 🎫- JIRA Ticket Link(s)## Type of Change 🛠️- [ ] Bug fix- [ ] New feature- [ ] Enhancement- [ ] Documentation update- [ ] Other (please specify): ________## Area of Impacts 🎯Please specify the area(s) of the codebase that this pull request impacts.- [ ] Frontend/UI- [ ] Backend/Server- [ ] Database- [ ] Infrastructure/Deployment- [ ] Performance- [ ] Security- [ ] Documentation- [ ] Testing- [ ] Other (please specify): ________## Multisite Impact 🌐Does this PR code changes impact any other currently live site in the multisite environment?- [ ] Yes- [ ] No- If Yes, please describe the impacted site(s) and the nature of the impact:## Testing Steps ✔️Describe the testing performed to ensure these changes work as intended.## Screenshots (if applicable) 🖼️Include any relevant screenshots to visually showcase the changes.## Checklist ✅- [ ] I have tested these changes locally.- [ ] I have ensured that my code follows the coding standards of WPVIP.- [ ] I have documented any necessary changes.- [ ] My changes do not introduce new errors or warnings.- [ ] I have reviewed my code for potential security issues.- [ ] I have updated the documentation (if applicable).- [ ] I have requested code review.
At Trew Knowledge we have some scaffolding tools to help us get started.We have 3 theme generators.
A Block Theme generator ( yo trewknowledge )
A Hybrid Theme generator ( yo trewknowledge:hybrid )
A Classic Theme generator ( yo trewknowledge:legacy )
For the most part, we don’t use the Classic Theme generator anymore. If you are not interested in working on a Full Site Editing theme, use the hybrid option. The classic generator will be deprecated soon.
Run yo trewknowledge in the terminal. It will then prompt you to answer a couple of questions about the theme. After that, it will generate a block theme for you.