# Bioschemas Profile Rendering Documentation

## :mag: Aim

The goal of this work is to enable automated rendering of Bioschemas profiles on the website as soon as their JSON-LD serialization on GitHub is updated.

This diagram illustrates how files are routed through the three main entities: DDE, Bioschemas specifications and Bioschemas website repositories.


This workflow is supported by a [GitHub action](https://github.com/BioSchemas/specifications/blob/profile-auto-generation/.github/workflows/generate_profile_workflow.yml) which is fired at each `git push` to the specification repository.

## :memo: Step by step walkthrough
In this section you will find the steps to follow in order to render a bioschemas profile on the Bioschemas website.
In addition to a detailed explanation to the automated (Github Actions) and the manual process to be conducted.

When a community decides to create a new bioschemas profile or update/edit an existing one they should follow theses steps:

**Case new profile:**
If we will create the ComputationalTool profile for the first time:

1. You will create your profile in DDE, there is a specific demo for it in this [doc](). Or if you are more confortable with the Bioschemas profile, you will push your JSON-LD in the specifications repo under ProfileName/Version.json.
Now and your JSON-LD is pushed to the Specifications repo (whether manually or via DDE), you or someone from the Bioschemas Community should create a [pull request]([https:/](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests)/) for it.

1. At this point, and before merging the PR, there are some important manual configurations to be conducted:
1. Add your new profile, with the appropriate version, to the [profile versions config file](https://github.com/BioSchemas/bioschemas.github.io/blob/profile-auto-generation/_data/profile_versions.yaml).
1. Add a column with your profile's **groups**, **get_redirect_from**, and **cross_walk_url**, in the [metadata mapping file](https://github.com/BioSchemas/bioschemas.github.io/blob/profile-auto-generation/_data/metadata_mapping.csv)
* group:
* get_redirect_from:
* cross_walk_url: The URL of the last version/draft csv mapping file 
1. ==To Check:== We still are not sure, but we may need to edit some config files in the DDE repository.
1. The admin should check all the config files before [merging](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request) the PR. Once merged a [workflow](https://github.com/BioSchemas/specifications/blob/profile-auto-generation/.github/workflows/generate_profile_workflow.yml) that will automatically render the bioschemas profile will fire (Note: it's written with [Github Actions](https://github.com/features/actions)).
To follow the workflow's steps, go to the [actions](https://github.com/BioSchemas/specifications/actions/workflows/generate_profile_workflow.yml) in the sepcifications repo. Then, open your wokflow.
==The action will:==
* Clone the **specification repository** and retreive the last commit
* Fetch the name and the path of the updated/added profile.
* Setup Python 3.8 and install the appropraite dependencies
* Clone the **[website](https://github.com/BioSchemas/bioschemas.github.io) repository**
* Execute the **python script**: it maps each field of the JSON-LD to properties and specifications and generate a YAML File that can be rendered by Jekyll.
* Setup the Github TOKEN, so we can publish into the website repo.
* Commit and push the changes in the website repository in a branch in which the name is today's date. e.g: 2022-08-17.
1. Now, if you go to the [bioschemas repository branches](https://github.com/BioSchemas/bioschemas.github.io/branches), you should find the generated branch.
1. Now, just merge it to Master branch and your profile will be taken into consideration in the [bioschemas website](https://bioschemas.org/profiles/).

**Case existing profile:**
There is no big difference. In this case you will simply edit an existing DDE Profile or add a new json-ld with a new version/draft of the profile directly in the specifiactions repository.
A pull request should be created, all the manual steps detailed above should be followed and once merged the github action will fire.

## :bulb: Future work

==TODO== How to deal with errors in this automated process? What should happen if we face a problem

- when generating the JSON-LD in DDE ?
- in the generation of the YML file ?
- in the commit/push to the website repo ?
- when rendering the website with Jekyll ?

==TODO== We should have an automated process that notifies appropriate third parties when a problem occur.

## :pushpin: Summary
- [x] Aim of the work
- [x] Workflow Steps
- [x] Perspectives