CONTRIBUTING.md

@@ -0,0 +1,112 @@
+# CONTRIBUTING
+
+Thanks for contributing!
+We welcome any and all kinds of contribution, including:
+- bug fixes and code contributions
+- ideas for new features
+- testing
+- documentation improvements
+- general suggestions on how we can do better
+- ...
+
+
+## Development environment setup
+
+This project is using [hatch](https://hatch.pypa.io), a modern Python project manager.
+Please refer to their [official documentation](https://hatch.pypa.io/latest/install/) for installation instructions for your system.
+
+After installation, you can use ``hatch`` to execute specific tasks, which are defined in ``pyproject.toml`` (see individual subheadings below).
+Alternatively, ``hatch`` can provide you with a development shell with the necessary packages:
+
+```
+hatch shell
+```
+
+Presently, this work require a patched linkml installation.
+The patch(es) are listed in `patches/`.
+The script `tools/patch_linkml` documents how they need to be applied.
+This script can be used to patch a local installation, and is also executed in the actions that validate the included data models.
+In order to apply the patch, run
+
+```
+bash tools/patch_linkml
+```
+
+### Documentation
+
+- To *build* the documentation locally, run
+
+```
+hatch run docs:build
+```
+
+- To *serve* the documentation locally, run
+
+```
+hatch run docs:serve
+```
+
+### Model checks
+
+This repo uses a [schema linter](https://linkml.io/linkml/schemas/linter.html) with a configuration in ``.linkmllint.yaml`` to first validate schemas (=models) against the [LinkML Metamodel](https://linkml.io/linkml/schemas/metamodel.html) and then linting them.
+At the same time, the check will also generate various other output formats (JSON-LD context, JSON schema, owl, and Python classes) from the ``<model-name>.yaml`` files to potentially reveal "hidden" issues.
+
+
+- To perform this check on *all models*, run
+
+```
+hatch run check:models
+```
+
+- To perform this check on a *specific model*, e.g., ``flat-data/unreleased.yaml``, run
+
+```
+hatch shell
+make checkmodel/flat-data/unreleased
+```
+
+### Example conversion
+
+Each schema has example data used for testing.
+An example data file corresponds to a class from the schema file.
+The file organization looks as follows:
+
+```
+src
+└── schema-name
+    ├── unreleased
+    │   ├── examples        <- contains data that gets validated
+    │   │   ├── class-name.json
+    │   │   ├── class-name.rdf
+    │   │   └── class-name.yaml     <- starting format
+    │   ├── extra-docs
+    │   │   └── about.md
+    │   └── validation       <- files with required configurations
+    │       ├── class-name.invalid.cfg.yaml
+    │       └── class-name.valid.cfg.yaml      
+    └── unreleased.yaml             <- the schema file
+```
+
+The command 
+
+```
+hatch run check:examples
+```
+
+performs the following: It 
+
+- validates example data within ``examples`` according to configurations in ``validation``
+- converts example ``.yaml`` data into ``.json`` and ``.rdf``
+
+For other formats, e.g., ``ttl``, ``linkml-convert`` can be used to convert data from one form to another, following a schema:
+
+```
+hatch shell
+linkml convert -o ds.ttl -s src/flat-data/unreleased.yaml --target-class-from-path --infer src/flat-data/unreleased/examples/Dataset-1.yaml
+```
+
+
+## Useful hints for a contribution workflow
+
+* Because LinkML allows imports from other schemas, there may be more to the classes or slots you see defined in any given file.
+In order to figure out easily which slots are available or even required, we recommend that you **render the documentation locally**, as this allows you to browse through the classes and discover also information that comes from other schemas. 

README.md

@@ -6,29 +6,7 @@ https://concepts.inm7.de
 
 ## How to...
 
-Install (in a virtualenv)
+Please see [CONTRIBUTING.md](CONTRIBUTING.md) for installation instructions and other helpful guides.
-
-```
-pip install -r requirements.txt
-```
-
-Build docs:
-
-```
-make
-```
-
-Serve docs locally
-
-```
-mkdocs serve
-```
-
-Presently, this work require a patched linkml installation. The patch(es) are
-listed in `patches/`. The script `tools/patch_linkml` documents how they need
-to be applied. This script can be used to patch a local installation, and is
-also executed in the actions that validate the included data models.
-
 
 ## Acknowledgements