Improve documentation (#1019)

* Improve documentation

* add contributing

* fix indents

* update links

* Fix links

* fixed links

* how to setup local env

* copy and past from jetpack

* fix

* Update CONTRIBUTING.md

Co-authored-by: Jeremy Herve <[email protected]>

* Update CONTRIBUTING.md

Co-authored-by: Konstantin Obenland <[email protected]>

* Update CONTRIBUTING.md

Co-authored-by: Konstantin Obenland <[email protected]>

* Update docs/translations.md

Co-authored-by: Konstantin Obenland <[email protected]>

* Update docs/translations.md

Co-authored-by: Konstantin Obenland <[email protected]>

* remove jekyll code

* fix links

* Add docs for unit tests

---------

Co-authored-by: Jeremy Herve <[email protected]>
Co-authored-by: Konstantin Obenland <[email protected]>

Author: 3 people

.distignore

@@ -16,6 +16,7 @@ _site
 bin
 CHANGELOG.md
 CODE_OF_CONDUCT.md
+CONTRIBUTING.md
 composer.json
 composer.lock
 Dockerfile
@@ -40,4 +41,4 @@ readme.md
 SECURITY.md
 src
 tests
-vendor
+vendor

CHANGELOG.md

@@ -530,7 +530,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 * Normalize attributes that can have mixed value types
 
-## [1.3.0] 2023-12-05
+## [1.3.0] - 2023-12-05
 
 ### Added
 

CODE_OF_CONDUCT.md

@@ -60,7 +60,7 @@ representative at an online or offline event.
 
 Instances of abusive, harassing, or otherwise unacceptable behavior may be
 reported to the community leaders responsible for enforcement at
-https://developer.wordpress.com/contact/?g21-subject=Code%20of%20Conduct.
+<https://developer.wordpress.com/contact/?g21-subject=Code%20of%20Conduct>.
 All complaints will be reviewed and investigated promptly and fairly.
 
 All community leaders are obligated to respect the privacy and security of the
@@ -116,13 +116,13 @@ the community.
 
 This Code of Conduct is adapted from the [Contributor Covenant][homepage],
 version 2.0, available at
-https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+<https://www.contributor-covenant.org/version/2/0/code_of_conduct.html>.
 
 Community Impact Guidelines were inspired by [Mozilla's code of conduct
 enforcement ladder](https://github.com/mozilla/diversity).
 
 [homepage]: https://www.contributor-covenant.org
 
 For answers to common questions about this code of conduct, see the FAQ at
-https://www.contributor-covenant.org/faq. Translations are available at
-https://www.contributor-covenant.org/translations.
+<https://www.contributor-covenant.org/faq>. Translations are available at
+<https://www.contributor-covenant.org/translations>.

CONTRIBUTING.md

@@ -0,0 +1,41 @@
+# Contributing to ActivityPub for WordPress
+
+👍🎉 First off, thanks for taking the time to contribute! 🎉👍
+
+Developers of all levels can help — whether you can barely recognize a filter (or don’t know what that means) or you’ve already authored your own plugins, there are ways for you to pitch in.
+
+## Create Bug Reports
+
+If you find a bug, please [file a GitHub issue](https://github.com/Automattic/wordpress-activitypub/issues/). If you have write access, add the appropriate labels.
+
+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.
+
+## Write and submit a patch
+
+If you'd like to fix a bug or make an enhancement, you can submit a Pull Request. Before you get started, you'll want to **[set up your development environment.](docs/development-environment.md)**
+
+Once your development environment is ready, you can get started and [create your first Pull Request!](docs/pull-request.md)
+
+### Get started
+
+If you'd like to contribute but don't know where to get started, you can take a look at existing issues:
+
+- ["Good First Issues"](https://github.com/Automattic/wordpress-activitypub/labels/%5BType%5D%20Good%20First%20Issue) are a good entry point to get familiar with ActivityPub plugin's code base.
+- All issues labeled with [the "Good For Community" label](https://github.com/Automattic/wordpress-activitypub/issues?q=is%3Aopen+sort%3Aupdated-desc+label%3A%22Good+For+Community%22) are fair game. That's a great way to contribute new features and fix small issues within the ActivityPub plugin.
+
+### We’re Here To Help
+
+We encourage you to ask for help at any point. We want your first experience with the ActivityPub plugin to be a good one, so don’t be shy. If you’re wondering why something is the way it is, or how a decision was made, please create an issue and prefix it with “Question:”.
+
+## Translate the plugin
+
+If you speak a foreign language, you can help translate the ActivityPub plugin into your own language. [here is how.](docs/translations)
+
+## License
+
+The ActivityPub plugin is licensed under the [MIT](https://github.com/Automattic/wordpress-activitypub/blob/trunk/LICENSE) license.
+
+All materials contributed should be compatible with the MIT and GPLv2 license. This means that if you own the material, you agree to license it under the MIT license. If you are contributing code that is not your own, such as adding a component from another Open Source project, or adding an `npm` package, you need to make sure you follow these steps:
+
+1. Check that the code has a license. If you can't find one, you can try to contact the original author and get permission to use, or ask them to release under a compatible Open Source license.
+2. Check the license is compatible with MIT and [GPLv2](http://www.gnu.org/licenses/license-list.en.html#GPLCompatibleLicenses), note that the Apache 2.0 license is *not* compatible.

FEDERATION.md

@@ -31,12 +31,9 @@ In order to authenticate activities, Mastodon relies on HTTP Signatures, signing
 
 Mastodon requires all `POST` requests to be signed, and MAY require `GET` requests to be signed, depending on the configuration of the Mastodon server.
 
-More information on HTTP Signatures, as well as examples, can be found here: https://docs.joinmastodon.org/spec/security/#http
+More information on HTTP Signatures, as well as examples, can be found here: <https://docs.joinmastodon.org/spec/security/#http>
 
 ## Additional documentation
 
-- Plugin Description: https://github.com/Automattic/wordpress-activitypub?tab=readme-ov-file#description
-- Frequently Asked Questions: https://github.com/Automattic/wordpress-activitypub?tab=readme-ov-file#frequently-asked-questions
-- Installation Instructions: https://github.com/Automattic/wordpress-activitypub?tab=readme-ov-file#installation
-- Upgrade Notice: https://github.com/Automattic/wordpress-activitypub?tab=readme-ov-file#upgrade-notice
-- Changelog: https://github.com/Automattic/wordpress-activitypub/blob/trunk/CHANGELOG.md
+- Plugin Documentation: [docs/readme.md](docs/readme.md)
+- Changelog: <https://github.com/Automattic/wordpress-activitypub/blob/trunk/CHANGELOG.md>

docs/Gemfile

@@ -0,0 +1,101 @@
+# Setting up your environment
+
+## Overview
+
+In order to start developing the ActivityPub plugin you want to have access to a WordPress installation where you can install the plugin and work on it.
+
+To do that you need to set up a WordPress site and give it the ability to run your local build of the ActivityPub plugin code repository.
+
+There are several ways to achieve this, listed in the next section.
+
+## Get started with development
+
+### Clone the repository
+
+Before you get started, we recommend that you set up a public SSH key setup with GitHub, which is more secure than saving your GitHub credentials in your keychain. There are more details about [setting up a public key on GitHub.com](https://help.github.com/en/articles/adding-a-new-ssh-key-to-your-github-account).
+
+Fork this repository to your own GitHub account and clone it to your local machine.
+
+### Local development
+
+To run the ActivityPub plugin in a local WordPress environment, you can use `wp-env` or Docker.
+
+### wp-env
+
+`wp-env` lets you easily set up a local WordPress environment for building and testing plugins and themes. It’s simple to install and requires no configuration.
+
+To get started, install `wp-env` by running the following command in the root of the ActivityPub plugin directory:
+
+```bash
+npm install
+```
+
+Then, start the local environment by running:
+
+```bash
+npm run env-start
+```
+
+This will start a local WordPress environment with the ActivityPub plugin installed and activated. You can open the WordPress site in your browser by visiting `http://localhost`.
+
+To stop the environment, run:
+
+```bash
+npm run env-stop
+```
+
+### Docker
+
+If you prefer to use Docker, you can use the `docker-compose.yml` file in the root of the ActivityPub plugin directory.
+
+To start the environment, run:
+
+```bash
+docker-compose up -d
+```
+
+This will start a local WordPress environment with the ActivityPub plugin installed and activated.
+
+You can open the WordPress site in your browser by visiting `http://localhost:8076`.
+
+## Running Tests
+
+You can now run the test suite using either npm or composer:
+
+```bash
+# Using npm
+npm run env-start
+npm run env-test
+
+# Using composer
+wp-env start
+composer run test:wp-env
+```
+
+### PHPUnit Arguments
+
+Both commands support additional PHPUnit arguments. Add them after `--`:
+
+```bash
+# Run a specific test
+npm run env-test -- --filter=test_migrate_to_4_1_0
+
+# Run tests in a specific file
+npm run env-test -- tests/includes/class-test-migration.php
+
+# Run tests with a specific group
+npm run env-test -- --group=migration
+
+# Run tests with verbose output
+npm run env-test -- --verbose
+
+# The same works with composer
+composer run test:wp-env -- --filter=test_migrate_to_4_1_0
+```
+
+Common PHPUnit arguments:
+- `--filter`: Run tests matching a pattern
+- `--group`: Run tests with a specific @group annotation
+- `--exclude-group`: Exclude tests with a specific @group annotation
+- `--verbose`: Output more verbose information
+- `--debug`: Display debugging information