> ## Documentation Index > Fetch the complete documentation index at: https://engineering.trewknowledge.com/llms.txt > Use this file to discover all available pages before exploring further. # Creating a new Project Most of our code is available on GitHub. You can find our repositories at the [Trew Knowledge GitHub Org](https://github.com/trewknowledge) or at the [WP VIP GitHub Org](https://github.com/wpcomvip). 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. ## Initial Commit For WP VIP projects it is all done for us using the [VIP Go Skeleton](https://github.com/Automattic/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](https://github.com/trewknowledge/vip-go-skeleton), click on the "Use this template" button and follow the instructions. ## Build, test & deploy 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. ### WordPress VIP 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. ### Non-WP VIP Projects 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. ### Sample Configuration Files ```yml .circleci/config.yml theme={null} version: 2 jobs: 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") ``` ```yml .github/workflows/main.yml theme={null} name: main on: [push] jobs: deploy: runs-on: [ubuntu-latest] if: github.ref == 'refs/heads/main' || github.ref == 'refs/heads/develop' steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: 18 - name: Install Block Plugin Packages working-directory: ./plugins/project-name-blocks run: npm ci - name: Build Blocks working-directory: ./plugins/project-name-blocks run: npm run build - name: Install Theme Packages working-directory: ./themes/theme-name run: npm ci - name: Build Theme working-directory: ./themes/theme-name run: npm run build - name: Cleaning up before deployment run: | rm -fr .git rm -fr .github - name: Deploy to Production if: github.ref == 'refs/heads/main' uses: trewknowledge/rsync-deploy@master env: DEPLOY_KEY: ${{ secrets.DEPLOY_KEY }} ARGS: "-az" FOLDER: "" SERVER_PORT: 22 SERVER_IP: ${{ secrets.SERVER_IP }} USERNAME: ${{ secrets.USERNAME }} SERVER_DESTINATION: ${{ secrets.SERVER_DESTINATION }} - name: Deploy to Develop if: github.ref == 'refs/heads/develop' uses: trewknowledge/rsync-deploy@master env: DEPLOY_KEY: ${{ secrets.DEPLOY_KEY_DEVELOP }} ARGS: "-az" FOLDER: "" SERVER_PORT: 22 SERVER_IP: ${{ secrets.SERVER_IP_DEVELOP }} USERNAME: ${{ secrets.USERNAME_DEVELOP }} SERVER_DESTINATION: ${{ secrets.SERVER_DESTINATION_DEVELOP }} - name: action-slack uses: 8398a7/action-slack@v2.4.2 with: status: ${{ job.status }} author_name: "Github Slack Action" only_mention_fail: "here" env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }} ``` ### Sample repository secrets 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. | Key | Value | | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **SERVER\_DESTINATION** | \~/sites/site-folder-name/wp-content | | **SERVER\_IP** | environment.ssh.wpengine.net | | **SLACK\_WEBHOOK\_URL** | [https://hooks.slack.com/services/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](https://hooks.slack.com/services/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) | | **USERNAME** | sshusername | | **DEPLOY\_KEY** | This is your private ssh key that will be used to connect to the server | ## Branch Protection 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. * Require status checks to pass before merging. * Require branches to be up to date before merging. ## Pull Request templates 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. ```markdown .github/pull_request_template.md theme={null} ## 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: ## Post-Deployment Actions Required 🚦 > List any manual or follow-up steps that must be completed *after this PR is deployed*. > If none are required, remove this section. Examples: * Menu or navigation configuration * Updating WP/Admin/VIP Dashboard settings * Running Elasticsearch / Enterprise Search sync * Cache flush or reindex * Content updates or migrations ### **Required actions:** * List the required actions here ## 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. ``` ## Generate a new Theme At Trew Knowledge we have some scaffolding tools to help us get started. We have 3 theme generators. 1. A Block Theme generator ( `yo trewknowledge` ) 2. A Hybrid Theme generator ( `yo trewknowledge:hybrid` ) 3. 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. ### How to use the generators 1. Make sure your copy of the [TK-Quickstart repository](https://github.com/trewknowledge/TK-Quickstart) is up to date. 2. 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.