Update README.md

CONTRIBUTING.md

@@ -0,0 +1,88 @@
+# How to contribute <a name="top"/>
+
+openMINDS is by design an open-source, community-driven project incorporating input and feedback from all community members independent of their scientific background.
+
+**Do not be shy!** We, the openMINDS development team, rely on you, as a community member, to get in touch if you have general feedback or a request for a new feature, want to report a bug or have a question. Depending on the type of message for us, you can either contact us via our support-email or via an issue on our GitHub repositories. You are also welcome to contribute to discussion in the issue tracker.
+
+For more details please go to: [Report & ask questions](#report-questions)
+
+**Help us directly!** Contributions from outside the openMINDS development team are always very welcome. If you spot a bug and know how to fix it, if you want to extend existing schemas and/or metadata models, or develop new schemas and/or metadata models, feel free to fork this repository and open a pull request with your changes. For larger changes, please raise an issue beforehand to get feedback from the openMINDS development team and the community.
+
+For more details please go to: [Direct contributions](#direct-contributions)
+
+**Be nice!** Contributing to openMINDS should be a harassment-free experience for everyone, regardless of age, body size disability, ethnicity, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+For more details please go to: [Code of conduct](#code-of-conduct)
+
+---
+
+## Report & ask questions <a name="report-questions"/>
+
+In particular, general feedback and questions are welcome through our support-email: **`[email protected]`**
+
+It is also possible to request new features or report bugs this way, but in these cases we prefer if you could raise an issue on the respective GitHub repository (see below).
+
+If you write us an email, please make sure that you provide a meaningful subject that describes your concern. If your concern is not of general nature, please name the affected GitHub repository and file in your email. In particular for bug reports, provide us with a screen shot or copy of your error message (where applicable). 
+
+You can also report and ask questions through the issue tracker of our GitHub repository. If your concern is of general nature, please consider raising an issue on the  [central openMINDS repository](https://github.com/HumanBrainProject/openMINDS). In contrast, bug reports and feature requests are better raised as issue on the affected openMINDS repository.
+
+If you raise an issue, please make sure that you provide a short meaningful title and a more detailed description that declares your concern. In particular for bug reports, provide us with a screen shot or copy of your error message (where applicable). 
+
+[BACK TO TOP](#top)
+
+## Direct contributions <a name="direct-contributions"/>
+
+If you want to contribute to the openMINDS_generator directly, feel free to fork it and open pull requests with your changes. Note, that larger changes and new features should be first raised and discussed as an issue before making a pull request. Minor bug fixes can, of course, still be made directly as a pull request without raising an issue first.
+
+For all contributions, make sure that you describe well what you plan to do / have done to speed up the evaluation / review process of your issue / pull request. The assigned member of the openMINDS development team will get back to you as soon as possible to discuss or give the blessing to your contribution. Note that, all contributing community members are welcome to provide comments on active issues and pull requests. 
+
+[BACK TO TOP](#top)
+
+## Code of conduct <a name="code-of-conduct"/>
+
+**Contributing to openMINDS should be a harassment-free experience for everyone** regardless of age, body size disability, ethnicity, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+#### Our pledge
+
+In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+#### Our standards
+
+Examples of behavior that contributes to creating a positive environment include:  
+**+** using welcoming and inclusive language  
+**+** being respectful of differing viewpoints and experiences  
+**+** gracefully accepting constructive criticism  
+**+** focusing on what is best for the community  
+**+** showing empathy towards other community members  
+
+Examples of unacceptable behavior by participants include:  
+**-** use of sexualized language or imagery  
+**-** unwelcome sexual attention or advances  
+**-** trolling, insulting/derogatory comments, and personal or political attacks  
+**-** public or private harassment  
+**-** publishing others' private information (e.g., email address) without explicit permission  
+**-** other conduct which could reasonably be considered inappropriate in a professional setting  
+
+#### Our responsibility
+
+Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
+
+#### Scope
+
+This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.
+
+#### Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team via **`[email protected]`**
+
+All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
+
+#### Attribution
+
+This code of conduct is adapted from the [Contributor Covenant](http://contributor-covenant.org), [version 1.4](http://contributor-covenant.org/version/1/4).
+
+[BACK TO TOP](#top)

README.md

@@ -1,31 +1,98 @@
-# Welcome to openMINDS!
+<a href="https://github.com/HumanBrainProject/openMINDS_generator/blob/main/img/openMINDS_generator_logo.png">
+    <img src="https://github.com/HumanBrainProject/openMINDS_generator/blob/main/img/openMINDS_generator_logo.png" alt="openMINDS logo" title="openMINDS" align="right" height="70" />
+</a>
 
-This is the repository for the generator scripts of
-[**openMINDS**](https://github.com/HumanBrainProject/openMINDS)
+# openMINDS_generator <a name="welcome"/>
 
-These scripts allow the generation of the output formats HTML, schema.json and
-python from the template language used to define the openMINDS schemas.
+The **openMINDS_generator** is part of the **open** **M**etadata **I**nitiative for **N**euroscience **D**ata **S**tructures, short **openMINDS**. It contains the **integration pipeline** which builds the [central openMINDS GitHub repository](https://github.com/HumanBrainProject/openMINDS), as well as a small **Python API** which enables the dynamic usage of the openMINDS schemas in your Python application. 
 
-In addition to this the python compiler allows the dynamic usage of openMINDS
-in your Python appication.
+openMINDS is the umbrella for a set of metadata models that can be used to describe neuroscience research products in graph databases (such as the EBRAINS Knowledge Graph). As research products, openMINDS considers data originating from human/animal studies or simulations (datasets), computational models (models), software tools (software), as well as metadata/data models (metaDataModels).
 
-Example:
+openMINDS is powered by [HBP](https://www.humanbrainproject.eu) (Human Brain Project) and [EBRAINS](https://ebrains.eu/). However, openMINDS is by design open-source and community-driven, looking for external contributions throughout the neuroscience community. 
 
-    import generator.openminds_helper
-    import generator.python_compiler
+Within EBRAINS, the openMINDS metadata models are adopted by the EBRAINS Knowledge Graph and Interactive Brain Atlas. In addition, openMINDS is currently in the process of being adopted by the Japan Brain/MINDS project.
 
+The openMINDS development team currently unites knowledge from the EBRAINS Curation Service, the EBRAINS Knowledge Graph, the EBRAINS Atlas, and the INCF Knowledge Space teams. 
 
-    helper = generator.openminds_helper.OpenMINDS_helper()
-    copyright = generator.python_compiler.generate(helper.core.DATA__COPYRIGHT)
-    copyright_schema = generator.python_compiler.generate_file(helper.core.DATA__COPYRIGHT)
+#### What you can find here:
+1. [How to contribute](#how-to-contribute) 
+2. [openMINDS integration pipeline](#integration-pipeline)
+3. [openMINDS Python API](#python-api)
+4. [License & acknowledgements](#license-and-acknowledgements)
 
-    copyright_schema.year = 2020
-    copyright_schema.holder = "somebody"
+---
 
-    copyright_schema.save("test.json")
+## How to contribute <a name="how-to-contribute"/>
 
-This example generates a copyright schema object, for which the values can be
-set and it can be saved as openMINDS conform json.
+If you have general feedback or a request for a new feature, want to report a bug or have a question, please get in touch with us via our support-email: **`[email protected]`** (not active yet). 
 
-## License
-This work is licensed under the MIT License.
+If you spot a bug and know how to fix it, if you want to extend existing schemas and/or metadata models, or develop new schemas and/or metadata models, feel always free to also contribute directly by raising an issue and making a pull request on the respective GitHub repository. 
+
+For more information on how to contribute, please have a look at our [CONTRIBUTING](./CONTRIBUTING.md) document.
+
+[BACK TO TOP](#welcome)
+
+## openMINDS integration pipeline  <a name="integration-pipeline"/>
+
+The setup of the central openMINDS GitHub repository is maintained by the openMINDS integration pipeline. The pipeline is configured in such a way, that each commit on one of the openMINDS submodules hosting a metadata model will trigger a new build of the central openMINDS repository ensuring that its content is always up-to-date. 
+
+In summary, the integration pipeline does the following:
+1. It makes sure that each version branch the central openMINDS GitHub repository ingests the correct set of openMINDS metadata models as git-submodules. 
+2. It extracts the openMINDS vocabulary (schema types and properties) across all openMINDS versions and stores it on the main branch of the central openMINDS GitHub repository to facilitate central maintenance. The setup also allows to manually enrich this vocabulary with general definitions, human-readable labels, and references to vocabulary of other metadata initiatives.
+3. It interprets and extends the simplified openMINDS schema syntax to formal, well-known formats, such as JSON-Schema or HTML, and stores the resulting schema representation for each openMINDS version (stable and development) on the documentation branch of the the central openMINDS GitHub repository which is exposed as a [GitHub page](https://humanbrainproject.github.io/openMINDS/).
+
+
+[BACK TO TOP](#welcome)
+
+## openMINDS Python API <a name="python-api"/>
+
+The **openMINDS Python API** is also available at the [Pyhton Package Index](https://pypi.org/project/openMINDS/) and can be installed using `pip install` in your console:
+
+```console
+pip install openMINDS
+```
+
+As stated above, the openMINDS.compiler allows you the dynamic usage of openMINDS metadata models and schemas in your Python application for generating your own collection of openMINDS conform metadata representations (instances) as JSON-LDs. Here a small example:
+
+```python
+import openMINDS.compiler
+
+# initiate the helper class for the dynamic usage of a specific openMINDS version
+helper = openMINDS.compiler.Helper(version="v2.0.0")
+
+# initiate the collection into which you will store all metadata instances
+mycollection = helper.create_collection()
+
+# create a metadata instance for (e.g.) the openMINDS Person schema
+lyuba = mycollection.add_core_person(givenName="Lyuba")
+
+# add more metadata to a created instance
+mycollection.get(lyuba).familyName = "Zehl"
+
+# add connections to other metadata instances
+email_lyuba = mycollection.add_core_contactInformation(email="[email protected]")
+mycollection.get(lyuba).contactInformation = email_lyuba
+
+# save your collection
+mycollection.save("./myFirstOpenMINDSMetadataCollection/")
+```
+
+To learn in general about the available openMINDS metadata models, schemas and their required or optional metadata properties, please go the [central openMINDS GitHub repository](https://github.com/HumanBrainProject/openMINDS), or the full documentation on the EBRAINS Collaboratory (coming soon).
+
+Within the openMINDS.compiler you can also get an overview of the requirement of a schema and all its properties by using the `help_«X»` function:
+
+```python
+mycollection.help_core_person()
+```
+
+[BACK TO TOP](#welcome)
+
+## License & acknowledgements <a name="license-and-acknowledgements"/>
+
+openMINDS is licensed under the MIT License.
+
+**Logo:** The openMINDS logo was created by U. Schlegel, based on an original sketch by C. Hagen Blixhavn and feedback by L. Zehl.
+
+The metadata model specifications as well as surrounding code and tools were developed in part or in whole in the Human Brain Project, funded from the European Union’s Horizon 2020 Framework Programme for Research and Innovation under Specific Grant Agreements No. 720270, No. 785907, and No. 945539 (Human Brain Project SGA1, SGA2, and SGA3).
+
+[BACK TO TOP](#welcome)