docs: add contributors guide

README.md

@@ -29,3 +29,4 @@ The intention is to integrate many existing 2nix converters into this framework,
 
 - [Summary of the core concepts and benefits](/docs/concepts-and-benefits.md)
 - [How would this improve the packaging situation in nixpkgs](/docs/nixpkgs-improvements.md)
+- [Contributors Guide](/docs/contributors-guide.md)

docs/contributers-guide.md

@@ -0,0 +1,76 @@
+# dream2nix contributers guide
+
+## Contribute Translator
+
+In general there are 3 different types of translators
+
+1. pure translator
+
+   - translation logic is implemented in nix lang only
+   - does not invoke build or read from any build output
+
+2. IFD translator
+
+   - part of the logic is integrated as a nix build
+   - nix code is used to invoke a nix build and parse its results
+   - same interface as pure translator
+
+3. impure
+
+   - translator can be any executable program running outside of a nix build
+   - not constrained in any way (can do arbitrary network access etc.)
+
+### Add a new translator
+
+To add a new translator, execute the flakes app `contribute` which will generate a template for you. Then open the new `default.nix` file in an edtior
+
+The nix file must declare the following attributes:
+
+In case of a `pure` or `IFD` translator:
+
+```nix
+{
+  # function which receives source files and returns an attribute set
+  # which follows the dream lock format
+  translate = ...;
+
+  # function which receives source files and returns either true or false
+  # indicating if the current translator is capable of translating these files
+  compatiblePaths = ;
+
+  # optionally specify additional arguments that the user can provide to the
+  # translator to customize its behavior
+  specialArgs = ...;
+}
+```
+
+In case of an `impure` translator:
+
+```nix
+{
+  # A derivation which outputs an executable at `/bin/translate`.
+  # The executable will be called by dream2nix for translation
+  #
+  # The first arg `$1` will be a json file containing the input parameters
+  # like defined in /specifications/translator-call-example.json and the
+  # additional arguments required according to specialArgs
+  #
+  # The program is expected to create a file at the location specified
+  # by the input parameter `outFile`.
+  # The output file must contain the dream lock data encoded as json.
+  translateBin = ...;
+
+  # A function which receives source files and returns either true or false
+  # indicating if the current translator is capable of translating these files
+  compatiblePaths = ;
+
+  # optionally specify additional arguments that the user can provide to the
+  # translator to customize its behavior
+  specialArgs = ...;
+}
+```
+
+Ways of debugging your translator:
+
+- run the dream2nix flake app and use the new translator
+- temporarily expose internal functions of your translator, then use nix repl `nix repl ./.` and invoke a function via `translators.translators.{subsystem}.{type}.{translator-name}.some_function`