Docs: update to mention changelog and release changes (#1454)

* Docs: update to mention changelog and release changes

I also took the opportunity to expand the Pull Request documentation, and add a mention of Composer in the general development docs since the tool is important for general development.

* Add detail about patch release's readme.txt editing

Author: jeherve

.github/changelog/update-docs-pr-changelog-composer

@@ -0,0 +1,4 @@
+Significance: patch
+Type: changed
+
+Documentation: expand Pull Request process docs, and mention the new changelog process as well as the updated release process.

docs/development-environment.md

@@ -58,6 +58,18 @@ This will start a local WordPress environment with the ActivityPub plugin instal
 
 You can open the WordPress site in your browser by visiting `http://localhost:8076`.
 
+### Composer
+
+Composer is used to install development dependencies for the ActivityPub plugin, to run unit tests, and to manage changelog entries.
+
+To install Composer, follow the instructions on the [Composer website](https://getcomposer.org/).
+
+Once Composer is available on your machin, you can install dependencies for the project like so:
+
+```bash
+composer install
+```
+
 ## Running Tests
 
 You can now run the test suite using either npm or composer:

docs/pull-request.md

@@ -4,3 +4,55 @@ When you’re first starting out, your natural instinct when creating a new feat
 
 **It’s important to break your feature down into small pieces first**, each piece should become its own pull request.
 
+## Creating a pull request
+
+Once you know what the first small piece of your feature will be, follow this general process while working:
+
+### Create a new branch
+
+#### Branch Naming Scheme
+
+All changes should be developed in a new branch created from the `trunk` branch.
+
+Branches use the following naming conventions:
+
+* `add/{something}` -- When you are adding a completely new feature
+* `update/{something}` -- When you are iterating on an existing feature
+* `fix/{something}` -- When you are fixing something broken in a feature
+* `try/{something}` -- When you are trying out an idea and want feedback
+
+For example, you can run: `git checkout trunk` and then `git checkout -b fix/whatsits` to create a new `fix/whatsits` branch off of `origin/trunk`.
+
+The ActivityPub repo uses the following "reserved" branch name conventions:
+
+* `release/{X.Y.Z}` -- Used for the release process.
+
+### Develop, commit
+
+1. Start developing and pushing out commits to your new branch.
+    - Push your changes out frequently and try to avoid getting stuck in a long-running branch or a merge nightmare. Smaller changes are much easier to review and to deal with potential conflicts.
+    - Don’t be afraid to change, [squash](http://gitready.com/advanced/2009/02/10/squashing-commits-with-rebase.html), and rearrange commits or to force push - `git push --force-with-lease origin fix/something-broken`. Keep in mind, however, that if other people are committing on the same branch then you can mess up their history. You are perfectly safe if you are the only one pushing commits to that branch.
+    - Squash minor commits such as typo fixes or [fixes to previous commits](http://fle.github.io/git-tip-keep-your-branch-clean-with-fixup-and-autosquash.html) in the pull request.
+1. If you have [Composer installed](https://getcomposer.org/), you can run `composer install` and `composer lint [directory or files updated]` to check your changes against WordPress coding standards. Please ensure your changes respect current coding standards.
+1. If you end up needing more than a few commits, consider splitting the pull request into separate components. Discuss in the new pull request and in the comments why the branch was broken apart and any changes that may have taken place that necessitated the split. Our goal is to catch early in the review process those pull requests that attempt to do too much.
+
+### Create a changelog entry
+
+Before you push your changes, make sure you create a changelog entry. Those entries provide useful information to end-users and other developers about the changes you've made, and how they can impact their WordPress site.
+
+#### How do I create a changelog entry?
+
+You can use the `composer changelog:add` command to create a changelog entry, and then follow the prompt and commit the changelog file that was created for you.
+
+### Create your Pull Request
+
+When you feel that you are ready for a formal review or for merging into `trunk`, push your branch to GitHub and open a Pull Request.
+
+As you open your Pull Request, make sure you check the following:
+    - Make sure your Pull Request includes a changelog entry, or add the "Skip Changelog" label to the PR.
+    - Make sure all required checks listed at the bottom of the Pull Request are passing.
+    - Make sure your branch merges cleanly and consider rebasing against `trunk` to keep the branch history short and clean.
+    - If there are visual changes, add before and after screenshots in the pull request comments.
+    - If possible add unit tests,
+    - Provide helpful instructions for the reviewer so they can test your changes. This will help speed up the review process.
+

docs/release-process.md

@@ -15,9 +15,9 @@ Major and minor releases follow the same release process. These releases are cre
      npm run release
      ```
    - The script will:
-     - Prompt for the new version number
+     - Determine the new version number based on the unreleased changelog entries.
      - Update version numbers in relevant files
-     - Update the changelog
+     - Update `CHANGELOG.md` and `readme.txt` with the changelog entries
      - Create a new branch
      - Commit changes
      - Push to GitHub
@@ -46,18 +46,16 @@ Patch releases require a more manual process as they need to be created from the
 ### Steps
 
 1. **Restore Release Branch**
-   - Locate the most recent release branch (for `5.3.0` it was [#1371](https://github.com/Automattic/wordpress-activitypub/pull/1371)).
-   - If needed, recreate the branch from the last release tag.
-
-2. **Create Version PR**
-   - Base the version PR on PR [#1192](https://github.com/Automattic/wordpress-activitypub/pull/1192).
-   - The release script doesn't support releasing patch versions, so you'll need to manually update version numbers and changelog entries.
-   - Manually update version numbers in relevant files.
-   - Manually update changelog and readme.txt with the patch version number above the entries that will be part of the release.
-
-3. **Cherry-pick Changes**
-   - Identify merge commits from `trunk` that need to be included.
-   - Cherry-pick each merge commit into the release branch:
+   - Locate the most recent release branch (for `5.3.0` it was `release/5.3.0`, created via [#1371](https://github.com/Automattic/wordpress-activitypub/pull/1371)).
+   - Click "Restore branch" to recreate it.
+   - Locally, checkout that release branch you just restored: `git fetch origin release/5.3.0 && git checkout release/5.3.0`
+
+2. **Cherry-pick Changes into the release branch**
+   - Identify merge commits from `trunk` that need to be included. You can find them at the bottom of each PR:
+
+<img width="904" alt="image" src="https://github.com/user-attachments/assets/4c49c5bd-928c-44d2-b64b-39454baa8d9d" />
+
+   - Cherry-pick each merge commit into this branch:
      ```bash
      # Checkout the release branch.
      git checkout release/5.3.0
@@ -67,12 +65,15 @@ Patch releases require a more manual process as they need to be created from the
      ```
      > Note: The `-m 1` flag is required when cherry-picking merge commits. Merge commits have two parent commits - the first parent (`-m 1`) is the target branch of the original merge (usually the main branch), and the second parent (`-m 2`) is the source branch that was being merged. We use `-m 1` to tell Git to use the changes as they appeared in the main branch.
 
-4. **Resolve Conflicts**
-   - Common conflict areas:
-     - `CHANGELOG.md`
-     - `readme.txt`
-   - Resolve conflicts maintaining chronological order in changelog.
-   - Ensure version numbers are correct.
+   - Resolve merge conflicts that may come up as you cherry-pick commits.
+
+3. **Update changelog and version numbers**
+   - Run `composer changelog:write`. It will update `CHANGELOG.md` with the changelog entries you cherry-picked, and will give you a version number for that release.
+   - Edit `readme.txt` to paste the changelog entries from `CHANGELOG.md` into the `== Changelog ==` section.
+   - The release script doesn't support releasing patch versions, so you'll need to manually update version numbers in the different files (`activitypub.php`, `readme.txt`, and files that may have been changed to introduce an `unreleased` text).
+
+4. **Review and push your changes**
+   - Review your changes locally, and `git push` to push your changes to the remote.
 
 5. **Create Release**
    - On GitHub, navigate to the main page of the repository.