Fill naming jobs best practices documentation (#139)

Author: yann-eugone

docs/docs/best-practices/naming-jobs.rst

@@ -4,5 +4,44 @@ Naming Jobs
     | *There are only two hard things in Computer Science: cache invalidation and naming things.*
     | -- Phil Karlton
 
-todo
+
+Within the library, ``Jobs`` are identified with a ``name``, inside the ``JobRegistry``.
+A name is a simple ``string``, with the only requirement that every job must have a unique one.
+
+
+Decide on a convention
+------------------------------------------------------------
+
+There is no recommandation we can make here, you can use whatever notation you prefer:
+
+* ``ImportUser``
+* ``import_user``
+* ``import.user``
+* or anything else
+
+But we strongly recommend that you pick a convention and try to stick to it.
+
+
+In a Symfony project
+------------------------------------------------------------
+
+| Because this is how the Framework works, ``Jobs`` must be registered as services.
+| All services tagged with ``yokai_batch.job`` are collected in a ``CompilerPass``, and given to the ``JobRegistry``.
+
+You can tag manually all your jobs, and fill the job name withing the tag:
+
+.. literalinclude:: naming-jobs/symfony-manual-tag.php
+   :language: php
+
+You can autoconfigure all services with ``JobInterface`` to be tagged,
+and the job name will be the service id (most of the time the FQCN):
+
+.. literalinclude:: naming-jobs/symfony-autowire-tag.yaml
+   :language: yaml
+
+Finally, if you want all services to be tagged using autoconfigure, but still want to pick job names,
+you can implement ``JobWithStaticNameInterface`` in your jobs:
+
+.. literalinclude:: naming-jobs/symfony-interface-tag.php
+   :language: php
 

docs/docs/best-practices/naming-jobs/symfony-autowire-tag.yaml

@@ -0,0 +1,15 @@
+services:
+    _defaults:
+        autowire: true
+        autoconfigure: true
+
+    _instanceof:
+        Yokai\Batch\Job\JobInterface:
+            tags: ['yokai_batch.job']
+
+    App\:
+        resource: '../src/'
+        exclude:
+            - '../src/DependencyInjection/'
+            - '../src/Entity/'
+            - '../src/Kernel.php'

docs/docs/best-practices/naming-jobs/symfony-interface-tag.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Job;
+
+use Yokai\Batch\Bridge\Symfony\Framework\JobWithStaticNameInterface;
+use Yokai\Batch\Job\JobInterface;
+use Yokai\Batch\JobExecution;
+
+final class ImportUserJob implements JobInterface, JobWithStaticNameInterface
+{
+    public static function getJobName(): string
+    {
+        return 'import.user';
+    }
+
+    public function execute(JobExecution $jobExecution): void
+    {
+        // TODO: Implement execute() method.
+    }
+}

docs/docs/best-practices/naming-jobs/symfony-manual-tag.php

@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Job;
+
+use Symfony\Component\DependencyInjection\Attribute\AutoconfigureTag;
+use Yokai\Batch\Job\JobInterface;
+use Yokai\Batch\JobExecution;
+
+#[AutoconfigureTag('yokai_batch.job')]
+final class ImportUserJob implements JobInterface
+{
+    public function execute(JobExecution $jobExecution): void
+    {
+        // TODO: Implement execute() method.
+    }
+}