Implementing development workflows and guidelines for AP Repos

[smileBeda]

This is a short online of things that should be done on each repository of AP (not optional - IMO)

• Lock the main branches. For each repo there should be a setting under settings/rules/, which allows setup new rules for each branch, such as require signed commits, avoid deletion or requiring a PR before committing (the two most crucial IMO). This should be at least set up on the default branch which is usually main
• Do not let commits into dev or main that have not at least (n) reviewers giving an OK.
• Implement at least WPCS GitHub Workflow so that each and ever contributor is enforced to follow them. It can be agreed to have a custom ruleset however I do strongly recommend using the WordPress ruleset from WPCS. Usually, you should have a flow that goes like any branch > pr to dev > merge to dev > pr to main > merge to main and the GitHub workflow should kick in whenever push or pull request happen to develop, so things can be caught before releases (which is when develop goes to main, and tags are created). below I attached the workflow I use, it should work out of the box.
• For developers, they will have to install WPCS locally and declare the WordPress standard as the used sniff. Goes without saying that this will be perhaps a little annoying if someone never used it, since it will not only flag "serious" stuff, it will also flag things like using [] over array(), etc. These can be disabled in a custom ruleset (see the well ripened one of ClassicPress here, but again, I do not recommend this for a row of reasons, starting with "there are reasons for each and every rule in the WPCS sniff")
• Implement and require a proper changelog and enforce proper commit messages in the same style and fashion.
• Include version bumps on merges to relevant branches using the Semver
• Implement a CONTRIBUTING guideline (stored in a CONTRIBUTING.md file) where it is clearly explained what is expected from a contributor in technical details
• Implement a LICENSE (Github actually offers that when creating the repo, or, at least add it in the LICENSE file). This also removes the need of that annoying checkbox on the commit template.

Following a short list of things to do to get things "tested"

1. Publish things in one place and only in one place and where everyone can access them, forever, and only once they are ready to actually test. That would be for example GitHub > Tasks > Tag:Testing. Integrate GitHub Bot in slack (if you want to keep slack which I do not suggest) to alert @testers for example. You can also set actual GitHub Org members to be in special groups (such as testers) and communicate through that tool instead. However testers are usually not "tech savvy" so having a more "social approach" is better.
2. Provide actual downloadable assets for users to test. Users are not developers. They should test the functionality (of anything) the same way an end-user is going to do it, and an end user is not going to pull Git repos, for example. Pre-releases could be used for this, or (as long there is no "complex" release build etc process) simply one of the DEVs can zip up a package with the following command and attach it to a pre-release, for example: zip -r exact-name-of-asset.zip exact-name-of-asset -x "*/__MACOSX" -x "*/.DS_Store" -x "*/._*". This command is run in the directory where exact-name-of-asset lives as a unzipped folder (remember to remove any dev-assets from it before such as git files, etc). The DS_Store is Mac related, and required, if you work on one (as it otherwise breaks WP Upload mech).

This is a short online of things that should be done on each repository of AP (optional - but not optional IMO)

• Implement identical project structures on all repositories. I personally follow the PHP-PDS (also see this repo-branch for a more detailed view of how this looks like for example in a plugin). It is in the end up to the project defining its standard, but why re-invent the wheel, when someone did already...
• Implement requirements for actual code comments, structured so that PHPDOC can be run on it and documentation generated, rather than written and rewritten allover again (also refer to above shared repository-branch for an actual implementation thereof)
• At some point if Unit Tests are added, the same very repo-branch shared above also has working implementation of full WP Unit Testing workflows for GitHub already implemented so it can be used as a referece. Includes as well a release flow that can be handled fully inside the terminal, granting standardized release flow (note that this will require an additional GitHub setting to be changed, if implemented)

GH WorkFlow for WPCS:

name: WordPress Coding Standards

on:
  push:
    branches: [ develop ]
  pull_request:
    branches: [ develop ]

jobs:
  wpcs:
    name: WPCS Scan
    runs-on: ubuntu-latest
    env:
      REPO_NAME: ${{ github.event.repository.name }}

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Set up PHP
        uses: shivammathur/[email protected]
        with:
          php-version: '8.2.11'
          tools: composer, cs2pr
        
      - name: Set Composer allow-plugins config
        run: composer config --global allow-plugins.dealerdirect/phpcodesniffer-composer-installer true

      - name: Set Composer allow-plugins config
        run: composer config allow-plugins.dealerdirect/phpcodesniffer-composer-installer true

      - name: Install dependencies
        run: |
          composer global require wp-coding-standards/wpcs dealerdirect/phpcodesniffer-composer-installer --dev

      - name: Run WPCS
        run: |
          ~/.composer/vendor/bin/phpcs --standard=WordPress src/resources/* src/src/* src/index.php src/$REPO_NAME.php --report=checkstyle | cs2pr

[smileBeda]

Actually some of the things above are documented: https://github.com/aspirepress/.github/blob/093e3164439cc317482cc316c7f42f10f87a13ec/CONTRIBUTING.md
They just are not used as of yet. Thus leaving the checkboxes unchecked for now.

[asirota]

Where does using templates for issues and PRs fall into. Seems like a good thing to have to build high quality documentation around the content of both

https://docs.github.com/en/communities