Merge pull request #63 from metafacture/59-improveMaintainerGuidelines

Author: TobiasNx

MAINTAINING.md

@@ -0,0 +1,75 @@
+# Maintainer Guide
+
+## Updating the README in context of a Release
+
+Every release the following three pages should be checked and updated if needed:
+
+`docs/flux/flux-commands.md` -> for updating the list of Flux Commnads
+`docs/fix/Fix-User-Guide.md` -> for updating the glossary and the cookbook parts
+`docs/fix/Fix-functions.md` -> for updating the Fix Functions
+
+When updating the 
+
+## how to change [docs/flux/flux-commands.md](https://github.com/metafacture/metafacture-documentation/blob/master/docs/flux/flux-commands.md)
+
+The entries in [docs/flux/flux-commands.md](https://github.com/metafacture/metafacture-documentation/blob/master/docs/flux/flux-commands.md) describe the usage of commands used by flux.
+The content for `flux-commands.md` is automatically generated by running the metafacture runner without arguments, the output needs to be copyied to [docs/flux/flux-commands.md](https://github.com/metafacture/metafacture-documentation/blob/master/docs/flux/flux-commands.md)
+
+
+To add functions to this FLUX commands list one has to fill in the proper annotations in the correponding java classes. E.g.
+
+```
+reset-object-batch
+------------------
+- description:  Resets the downstream modules every batch-size objects
+- options:      batchsize (int)
+- signature:    Object -> Object
+- java class:   org.metafacture.flowcontrol.ObjectBatchResetter
+```
+
+is generated by reading following annotations in [ObjectBatchResetter.java](https://github.com/metafacture/metafacture-core/blob/511b4af8b993c85a33d6a18322258a195684d133/metafacture-flowcontrol/src/main/java/org/metafacture/flowcontrol/ObjectBatchResetter.java):
+
+```
+@Description("Resets the downstream modules every batch-size objects")
+@FluxCommand("reset-object-batch")
+@In(Object.class)
+@Out(Object.class)
+```
+
+The description of "options" is produced from all "public setter-methods", in this case:
+
+```
+ public void setBatchSize(final int batchSize) { ...
+```
+
+The option's name is produced by cutting away the "set" from the methods name, leaving "BatchSize" which is then lowercased. The parameter of this option is generated from the parameter type of the method - here an "int"eger.
+
+To add new example links to the playground or the metafacture runner or adjust existing links as well as the links to the JAVA code you have to update the flux example tsv: [`linksAndExamples.tsv`](https://github.com/metafacture/metafacture-documentation/blob/master/linksAndExamples.tsv). 
+
+```tsv
+flux-commands	code-link	example
+add-preamble-epilogue	https://github.com/metafacture/metafacture-core/blob/master/metafacture-formatting/src/main/java/org/metafacture/formatting/PreambleEpilogueAdder.java	https://metafacture.org/playground/?example=add-preamble-epilogue
+```
+
+First column is for the flux command, the second is for the code-link and the last is for a link to an example.
+
+## how to publish [docs/flux/flux-commands.md](https://github.com/metafacture/metafacture-documentation/blob/master/docs/flux/flux-commands.md)
+
+If you have updated some of these annotations, say "description", and these changes are released, generate a new `flux-commands.md`. Adjustments can always be published before a release unless it refers to an unreleased feature.
+
+Steps:
+
+- Download the latest released runner: https://github.com/metafacture/metafacture-core/releases
+- Unzip the downloaded runner distribution.
+- Check out the metafacture-documentation repo.
+- Change into that directory.
+- Run the runner in the this directory without arguments:./metafacture-core/flux.sh (note that the links will only generated if the git repo metafacture-documentation is checked out and the file [`linksAndExamples.tsv`](https://github.com/metafacture/metafacture-documentation/blob/master/linksAndExamples.tsv) is accessible).
+- Copy the generated output to [docs/flux/flux-commands.md](https://github.com/metafacture/metafacture-documentation/blob/master/docs/flux/flux-commands.md), modify the documentation spefic arrangements (i.e. the header) and commit it to http://metafacture.github.io/metafacture-documentation/docs/flux/flux-commands.html.
+
+## how to publish the changes for the fix documentation
+
+Check the README of the released metafacture-core tag: e.g. https://github.com/metafacture/metafacture-core/blob/metafacture-core-8.0.1/README.md#functions-and-cookbook
+
+Copy the `Best practices and guidelines for working with Metafacture Fix` and `Glossary` section to the corresponding section in `docs/fix/Fix-User-Guide.md` and the `Functions` section to `docs/fix/Fix-functions.md`. Adjust whitespaces and links if needed.
+
+Commit the the changes and let it review before merging it to the master. The master of the documentation repo should always correpond with the status of  current release and its features. Therefore only changes before a release that improve the documentation are allowed but none that refer to unreleased features.

docs/Documentation-Maintainer-Guide.md

@@ -5,7 +5,7 @@ parent: Fix
 nav_order: 2
 ---
 
-This page is a replication of the passage [Functions](https://github.com/metafacture/metafacture-core?tab=readme-ov-file#functions) of the Fix Readme.md. Status: [Core Release 8.0.0](https://github.com/metafacture/metafacture-core/releases/tag/metafacture-core-8.0.0)
+This page is a replication of the passage [Functions](https://github.com/metafacture/metafacture-core?tab=readme-ov-file#functions) of the Fix Readme.md. Status: [Core Release 8.0.1](https://github.com/metafacture/metafacture-core/releases/tag/metafacture-core-8.0.1)
 
 ### Functions