How to review a pull request for a Bioschemas Specification

A community member has created or updated a Bioschemas specification JSON-LD file and created a pull request. Here’s how to help review and merge it, so that the website and the DDE will be updated.

Step 1 ensure you have access to the appropriate channels and repositories

• You will need access to the ‘#spec_repo_updates’ channel on slack
• You will need to be able to perform merges in the Bioschemas specification repository
• You will need to be able to perform merges in the Bioschemas website repository

Step 2 Claim the pull request

• Reply to the slack notification on the pull request to inform others that you will be reviewing it
• Assign the pull request to yourself on GitHub

Step 3 - Verify that the JSONLD schema file is working properly and that the config file is up-to-date

• Go to the branch or fork of the Bioschemas specification repository that has the Bioschemas profile JSON-LD file that is the subject of the pull request
  • Does it load without error in the DDE?
  • Does it have the correct hierarchy (rdfs:subclassOf)?
  • Does the @context have the necessary iri’s?
  • Only if it is a __profile: Are the constraints properly expressed in the $validation?
• Verify that the configuration file in the bioschemas website repository is up-to-date
  • The configuration file needs to be updated only for brand new specifications, to update:
    • Create a new branch in the Bioschemas website repository with a suitable name to identify the intended outcome of the work, e.g. for a new 0.4 draft of the “example profile” we might have draft-example-0.4.
    • Find the _data/metadata_mapping.csv file. If it isn’t, add a row for the specification stating the specification name, working group name, and expected parent.
      • Note that the expected parent of a profile specification and type specification may be different:
        • For example: parent for FormalParameter profile is expected to be bioschemastypes:FormalParameter type, but the parent for FormalParameter type is expected to be schema:Intangible
    • Create a pull request from your branch to the parent branch.

Step 4 - Merge the pull requests

• IF you edited the metadata_mapping file in Step 3:
  • merge the pull request from your branch of the Bioschemas website to the parent branch.
  • This will ensure that the automated script has the information needed to automatically generate html files once triggered.
• Merge the pull request for the new/updated JSON-LD file that you reviewed to the master branch of the specification repository
  • This will trigger the GitHub action for automatically generating the corresponding page in the Bioschemas website.
  • The GitHub action will create a new branch of the Bioschemas website with the required changes
    • The branch will be named based on the date and time of when the GitHub action was triggered
      • It will follow the format YYYY_MM_DD-HH_MM_SS
    • The GitHub action will also automatically generate a pull request to merge the branch into master
• Merge the pull request that was generated by the GitHub action

Step 5 - Update the bioschemas specification in the DDE schema registry (to be automated and removed as a step)

• This step has been automated in a branch, but that branch has not been merged as it is dependant on the GitHub action in Step 4

Links and Further Reading

• Documentation on the automated JSON-LD-to-webpage conversion: https://hackmd.io/zGOAxx-BRfi4rDiaW9Rk4Q?both
• Documentation on the automated DDE-updates: https://github.com/bioschemas/bioschemas-dde
• About JSON-LD: https://json-ld.org/
• About JSON-schema: https://json-schema.org/
• The FAQ for the Data Discovery Engine (DDE): https://discovery.biothings.io/faq/dde