Merge pull request #24 from lloc/chore/documentation

Documenation added

Author: lloc

.distignore

@@ -10,8 +10,10 @@ coverage.xml
 .distignore
 .gitattributes
 .gitignore
+.phpcs.cache
 .phpunit.result.cache
 .scrutinizer.yml
+Changelog.md
 composer.lock
 mslsmenu.zip
 package.json
@@ -22,3 +24,4 @@ phpdoc.xml
 .phpcs.xml.dist
 phpunit.xml
 README.md
+AGENTS.md

.gitignore

@@ -2,9 +2,10 @@
 .phpunit.result.cache
 .phpcs.cache
 .idea/
+.phpcs.cache
 vendor/
 reports/
 mslsmenu/
 composer.lock
 mslsmenu.zip
-coverage.xml
+coverage.xml

AGENTS.md

@@ -0,0 +1,34 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+- `MslsMenu.php` is the WordPress bootstrap; add hooks here or split helpers into new subdirectories under `mslsmenu/` as needed.
+- `mslsmenu/` mirrors the shipping bundle; keep source and bundle in sync before release.
+- `languages/` stores translation assets; regenerate via `wp i18n make-pot` when strings move.
+- `tests/` houses Pest specs with Brain Monkey shims in `tests/Pest.php`; colocate fixtures with their specs.
+- `bin/` contains release tooling (`bin/git-release.sh`); prefer extending scripts over one-off commands.
+
+## Build, Test, and Development Commands
+- Run `composer install` after cloning to pull dev dependencies.
+- `composer test` executes the Pest suite with mocked WordPress APIs.
+- `composer analyze` runs PHPStan (level 5) against `MslsMenu.php`; keep it passing before pushing.
+- `composer coverage` enables Xdebug coverage for pull request evidence.
+- `composer build` triggers `bin/git-release.sh`, refreshing `mslsmenu/` and `mslsmenu.zip` for distribution.
+
+## Coding Style & Naming Conventions
+- Follow WordPress PHP standards: tabs for indentation, braces on new lines, no trailing commas.
+- Include `declare(strict_types=1);` in new entry points and document public APIs with PHPDoc.
+- Use `snake_case` for hook callbacks, `PascalCase` for classes, and `camelCase` for internal helpers unless a hook signature dictates otherwise.
+
+## Testing Guidelines
+- Place new specs in `tests/YourFeatureTest.php`; keep case names descriptive (`it('renders menu item')`).
+- Stub external WP functions with Brain Monkey setup blocks to keep tests deterministic.
+- Run `composer coverage` for behavioral changes and share the summary when coverage changes noticeably.
+
+## Commit & Pull Request Guidelines
+- Write short imperative subjects (≈50 chars) such as `Clean menu walker output`; batch related edits together.
+- Reference GitHub issues in the body (`Refs #123`) and list the commands you ran.
+- PRs should explain the problem, outline the fix, attach UI evidence when relevant, and confirm `composer test` plus `composer analyze`.
+
+## Release Packaging Tips
+- Bump the plugin header version in `MslsMenu.php` and sync the same value into `readme.txt` before building.
+- Run `composer build`, inspect the refreshed `mslsmenu/` contents, and spot-check the generated `mslsmenu.zip` before tagging.

README.md

@@ -4,6 +4,20 @@ MslsMenu
 [![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/lloc/MslsMenu/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/lloc/MslsMenu/?branch=master)
 [![codecov](https://codecov.io/gh/lloc/MslsMenu/graph/badge.svg?token=902NM9H2BW)](https://codecov.io/gh/lloc/MslsMenu)
 
-Adds the output of the Multisite Language Switcher to the one (or more) of your navigation menus(s)
+MslsMenu extends the Multisite Language Switcher by injecting a language picker into any registered WordPress navigation menu. Install it when you want users to toggle sites and languages without custom walkers.
 
-[Latest stable](https://wordpress.org/plugins/mslsmenu/) 
+## Install
+- From WordPress: search for “MslsMenu” under Plugins → Add New and activate it.
+- Manual: copy the `mslsmenu/` directory to `wp-content/plugins/` and activate the plugin.
+
+## Usage
+- Head to Appearance → Menus, add the “MslsMenu” item to your chosen menu, and arrange it like any other menu entry.
+- Configure Multisite Language Switcher as usual; MslsMenu reuses its site mappings automatically.
+
+## Develop
+- `composer install` pulls dev tools (Pest, PHPStan, Brain Monkey).
+- `composer test` runs the Pest suite; `composer analyze` performs static analysis.
+
+## Contribute
+- Review `AGENTS.md` for project conventions and release steps.
+- Latest release: https://wordpress.org/plugins/mslsmenu/

composer.json

@@ -13,29 +13,19 @@
     "brain/monkey": "2.*",
     "phpstan/phpstan": "^1.8",
     "szepeviktor/phpstan-wordpress": "^1.1",
-    "phpstan/extension-installer": "^1.1",
-    "wp-coding-standards/wpcs": "^3.0"
+    "phpstan/extension-installer": "^1.1"
   },
   "autoload-dev": {
       "files": [ "MslsMenu.php" ]
   },
   "scripts": {
     "test": "vendor/bin/pest",
     "coverage": "php -d xdebug.mode=coverage vendor/bin/pest --coverage",
-    "phpstan": "vendor/bin/phpstan analyze",
+    "analyze": "vendor/bin/phpstan analyze",
     "git-release": "bin/git-release.sh",
     "build": [
+      "@composer update --no-dev",
       "@git-release"
-    ],
-    "githooks": [
-      "if [ -e bin/githooks/pre-commit ]; then cp bin/githooks/pre-commit ./.git/hooks/; fi",
-      "if [ -e .git/hooks/pre-commit ]; then chmod 0755 .git/hooks/pre-commit; fi"
-    ],
-    "post-install-cmd": [
-      "@githooks"
-    ],
-    "post-update-cmd": [
-      "@githooks"
     ]
   },
   "authors": [
@@ -56,8 +46,7 @@
     "allow-plugins": {
       "composer/installers": true,
       "phpstan/extension-installer": true,
-      "pestphp/pest-plugin": true,
-      "dealerdirect/phpcodesniffer-composer-installer": true
+      "pestphp/pest-plugin": true
     }
   }
 }