Keruald: Difference between revisions
From Nasqueron Agora
(+phpcs.xml) |
|||
| (13 intermediate revisions by the same user not shown) | |||
| Line 19: | Line 19: | ||
|- | |- | ||
| keruald/dockerhub || Docker Hub, managing payload signatures | | keruald/dockerhub || Docker Hub, managing payload signatures | ||
|- | |||
| keruald/github || GitHub payloads for webhooks - managing payload signatures, class representations | |||
|- | |- | ||
| keruald/mailgun || Mailgun API client | | keruald/mailgun || Mailgun API client | ||
| Line 37: | Line 39: | ||
* a resource folder, not included in packages, if starting by an underscore _ or a dot . | * a resource folder, not included in packages, if starting by an underscore _ or a dot . | ||
* a name of a package if starting by a letter, e.g. keruald/commands for commands/ | * a name of a package if starting by a letter, e.g. keruald/commands for commands/ | ||
==== New version of a library ==== | |||
''This should be automated through Jenkins.'' | |||
To publish a new version of a library: | |||
* Create a new tag using library/version format, e.g. foo/1.2.3 | |||
* Run <code>./_utils/repo/export-commits-to-manyrepo.sh foo</code> | |||
* Tag with versions the new commits in the library repository (tags propagation isn't currently automated) | |||
** compare <code>git log</code> from monorepo and library repo | |||
** Add tag without any prefix in library repo, e.g. <code>git tag 1.2.3</code> | |||
=== How to import an existing library? === | |||
First, use [https://github.com/hraban/tomono tomono] in the PARENT DIRECTORY of the monorepo directory. | |||
If the name of the repository is NOT "core", export it as MONOREPO_NAME environment variable. | |||
For example, to import Keruald/GitHub library: | |||
<syntaxhighlight lang="console"> | |||
$ export MONOREPO_NAME=keruald | |||
$ echo "ssh://vcs@devcentral.nasqueron.org:5022/source/github.git github" | tomono --continue | |||
From ssh://devcentral.nasqueron.org:5022/source/github | |||
* [new branch] main -> github/main | |||
* [new tag] 0.1.0 -> github/0.1.0 | |||
* [new tag] 0.1.1 -> github/0.1.1 | |||
* [new tag] 0.2.0 -> github/0.2.0 | |||
* [new tag] 0.2.1 -> github/0.2.1 | |||
Updated 6 paths from the index | |||
</syntaxhighlight> | |||
Then follow the procedure for a new library to update the monorepo metadata. | |||
Don't forget to use <code>composer dump-autoload</code> to update your local Composer autoloader. | |||
=== How to create a new library? === | === How to create a new library? === | ||
To create a new library quux, we need a new empty manyrepo on DevCentral, a mirror on GitHub and to declare it on Packagist: | To create a new library quux, we need a new empty manyrepo on DevCentral, a mirror on GitHub and to declare it on Packagist: | ||
# | # Declare your library in <code>metadata.yml</code> | ||
# Regenerate shared files with <code>make | # Regenerate shared files with <code>make regenerate</code> (you need Python and Jinja2): that will add your repository to files like phpcs.xml | ||
# Create on DevCentral a new repository with a callsign starting by K for Keruald like KQUUX, and "quux" as shortname | # Create on DevCentral a new repository with a callsign starting by K for Keruald like KQUUX, and "quux" as shortname | ||
# Create on GitHub a new repository called keruald/quux | # Create on GitHub a new repository called keruald/quux | ||
| Line 50: | Line 87: | ||
Don't commit anything in newly created repos but contribute as usual by creating quux/ subdirectory in the monorepo | Don't commit anything in newly created repos but contribute as usual by creating quux/ subdirectory in the monorepo | ||
=== Troubleshoot === | |||
==== Error: Class "Keruald\GitHub\XHubSignature" not found ==== | |||
When a new library is added to the repository, a new entry is added to composer.json to provide that library. | |||
The Composer autoloader needs then to be updated with <code>composer dump-autoload</code>. | |||
=== Annex A. IDE configuration === | === Annex A. IDE configuration === | ||
Latest revision as of 16:29, 11 November 2024
Keruald is a set of libraries to build PHP applications.
Libraries
| Package name | Description |
|---|---|
| keruald/omnitools | General purpose library |
| keruald/globalfunctions | Wrapper to replace our old old sites "core.php" by calls to omnitools |
| keruald/commands | Create simple CLI application |
| keruald/report | Reporting library |
| keruald/health | Site health check |
| keruald/dockerhub | Docker Hub, managing payload signatures |
| keruald/github | GitHub payloads for webhooks - managing payload signatures, class representations |
| keruald/mailgun | Mailgun API client |
| keruald/database | Database abstraction layer |
| keruald/broker | Wrapper around brokers like RabbitMQ |
Developer guide
Contribution workflow
You'll find the general contribution guide at How to contribute code. Here some pointers specific for Keruald libraries.
We use a monorepo: clone the rKERUALD repository on DevCentral, you'll find your library as a direct subdirectory on it.
Each subdirectory matches:
- a resource folder, not included in packages, if starting by an underscore _ or a dot .
- a name of a package if starting by a letter, e.g. keruald/commands for commands/
New version of a library
This should be automated through Jenkins.
To publish a new version of a library:
- Create a new tag using library/version format, e.g. foo/1.2.3
- Run
./_utils/repo/export-commits-to-manyrepo.sh foo - Tag with versions the new commits in the library repository (tags propagation isn't currently automated)
- compare
git logfrom monorepo and library repo - Add tag without any prefix in library repo, e.g.
git tag 1.2.3
- compare
How to import an existing library?
First, use tomono in the PARENT DIRECTORY of the monorepo directory.
If the name of the repository is NOT "core", export it as MONOREPO_NAME environment variable.
For example, to import Keruald/GitHub library:
$ export MONOREPO_NAME=keruald
$ echo "ssh://vcs@devcentral.nasqueron.org:5022/source/github.git github" | tomono --continue
From ssh://devcentral.nasqueron.org:5022/source/github
* [new branch] main -> github/main
* [new tag] 0.1.0 -> github/0.1.0
* [new tag] 0.1.1 -> github/0.1.1
* [new tag] 0.2.0 -> github/0.2.0
* [new tag] 0.2.1 -> github/0.2.1
Updated 6 paths from the index
Then follow the procedure for a new library to update the monorepo metadata.
Don't forget to use composer dump-autoload to update your local Composer autoloader.
How to create a new library?
To create a new library quux, we need a new empty manyrepo on DevCentral, a mirror on GitHub and to declare it on Packagist:
- Declare your library in
metadata.yml - Regenerate shared files with
make regenerate(you need Python and Jinja2): that will add your repository to files like phpcs.xml - Create on DevCentral a new repository with a callsign starting by K for Keruald like KQUUX, and "quux" as shortname
- Create on GitHub a new repository called keruald/quux
- Publish on packagist
If the shortname is already taken on DevCentral, it's time to create a new task to provide a map of subdirectory/package repository.
Don't commit anything in newly created repos but contribute as usual by creating quux/ subdirectory in the monorepo
Troubleshoot
Error: Class "Keruald\GitHub\XHubSignature" not found
When a new library is added to the repository, a new entry is added to composer.json to provide that library.
The Composer autoloader needs then to be updated with composer dump-autoload.
Annex A. IDE configuration
PhpStorm
Clone the monorepo on your drive, then open it in PhpStorm to generate an .idea folder.
- Edit keruald.iml with this modules content to declare the code namespaces: https://devcentral.nasqueron.org/P300
- For code style, you can use https://github.com/nasqueron/codestyle/blob/main/JetBrains/php-codestyle.xml
