Skip to content

Latest commit

 

History

History
201 lines (128 loc) · 8.3 KB

README.md

File metadata and controls

201 lines (128 loc) · 8.3 KB

A Copier Template for LinkML Projects

This template uses the code-scaffolding tool copier to create a LinkML project. Copier supports code lifecycle management, allowing you to seamlessly incorporate updates into your project when the template is enhanced.

  • Early releases (0.1.x) maintain backwards compatibility with linkml-project-cookiecutter. This facilitates to experiment with the migration of existing cruft/cookiecutter-based projects.
  • Later releases starting with 0.2.0 will gradually give up compatibility.

The generated project uses just as preferred command runner, even in the 0.1.x releases.

The starting point of this template was linkml-project-cookiecutter (commit 1094cf2, date 2025-01-10). The code from the just command runner PR was also included (up to commit 3eb2522).

Prerequisites

The following are required and recommended tools for using this copier template and the LinkML project that it generates. This is all one-time setup, so if you have already done it skip to the next section! We assume that you have full internet access.

  • git / GitHub account

    Git is the version management system with which this template and your repository are managed. The template also assumes that you use GitHub for hosting your project which implies that you have a GitHub account.

  • Python >= 3.9

    LinkML tools are mainly written in Python, so you will need a recent Python interpreter to run this generator and to use the generated project.

  • pipx

    pipx is a tool for managing isolated Python-based applications. It is the recommended way to install the required tools. To install pipx follow the instructions here: https://pypa.github.io/pipx/installation/

  • Poetry

    Poetry is a Python project management tool. You will use it in your generated project to manage dependencies and build distribution files. Install Poetry by running:

    pipx install poetry

  • Poetry Dynamic Versioning Plugin:

    This plugin automatically updates certain version strings in your generated project when you publish it. Your generated project will automatically be set up to use it. Install it by running:

    pipx inject poetry "poetry-dynamic-versioning[plugin]"

  • copier

    Copier is a tool for generating projects based on a template (like this one!). It also allows re-configuring the projects and to keep them update if the original template changes. To insert dates into the template, copier requires jinja2_time in the copier environment. Install both with pipx by running:

    pipx install copier
pipx inject copier jinja2_time

  • just

    The project contains a justfile with pre-defined complex commands. To execute these commands you need just as command runner. Install it by running:

    pipx install just

Creating a new project

Step 1: Generate the project files

To generate a new LinkML project first create a new empty directory for the project and then run the following:

cd path/to/new/directory
copier copy --trust https://github.com/dalito/linkml-project-copier .

The --trust option is needed because the template uses the jinja_extension jinja2_time.

You will be prompted a few questions. The defaults are fine for most projects, but pick the name for your project carefully as it will also be used as project name on GitHub.

It is also possible to use non-default branches or specific tags via --vcs-ref which is useful when developing the template:

copier copy --trust --vcs-ref branch-name gh:dalito/linkml-project-copier ./path/to/destination

Step 2: Set up the LinkML project

Change to the folder your generated project is in.

Optionally customize your project if needed:

  • pass arguments to linkml generators via 'config.yaml' configuration file;
  • pass supported environment variables via '.env.public' configuration file;

Setup your project

cd my-awesome-schema  # using the folder example above
just setup

Step 3: Edit the schema

Edit the schema (the .yaml file) in the src/my_awesome_schema/schema folder with an editor of your choice.

Step 4: Validate the schema

just test

Step 5: Generate documentation locally

LinkML generates schema documentation automatically. The template includes the configuration for generating and publishing the documentation with GitHub whenever you push schema changes to GitHub. The published documentation can be found at a URL like this one: https://{github-user-or-organization}.github.io/{project-name}/

You can also preview the documentation locally before pushing to GitHub by running:

just testdoc

Step 6: Create a GitHub project

  1. Go to https://github.com/new and follow the instructions, being sure to NOT add a README or .gitignore file (this copier template will add those files for you)

  2. Add the remote to your local git repository:

    git remote add origin https://github.com/{github-user-or-organization}/{project-name}.git
git branch -M main
git push -u origin main

  3. Configure your repository for deploying the documentation as GitHub pages

  • Under Settings > Actions > General in section "Workflow Permissions" mark "Read repository and packages permission".
  • Under Pages in section "Build and Deployment":
    • Under "Source" select "Deploy from a branch"
    • Under "Branch" select "gh-pages" and "/ (root)"

Step 7: Register the schema

See How to register a schema

Making releases

See How to Manage Releases of your LinkML Schema

Migrating an existing project to use this template

This is a rough guide on the required steps. Feedback and suggestions for improvement based on your experiences are very welcome. The commands are written to be run at the root of your project.

  • Start with a clean state of the existing project (check with git status).

  • Create a new branch and activate it:

    git switch -c migrate-to-copier

  • Adapt your project and create a copier answers file (.copier-answers) by running:

    copier copy --trust --skip-tasks --vcs-ref=HEAD gh:dalito/linkml-project-copier .

    If you start from a linkml-project-cookiecutter based project, look into the .cruft.json file to find out which values you chose when you configured your project. Be sure to enter the same values when answering the copier questions.

  • Carefully review the changes that copier made to your project.

  • If you used a cruft/cookiecutter template before, you may delete the cruft file .cruft.json.

  • If you are happy, commit all changes to the migrate-to-copier branch.

  • To finalise the migration, merge the migrate-to-copier branch to your main branch.

Keeping your project up to date or changing its configuration

Copier allows you to update your project with changes from the template. You can also change the project by providing different answers to the questions than the last time.

To update your project with changes from the template and to reconfigure your project options, run:

copier update --trust --skip-tasks

To do a pure update without re-configuration run:

copier update --trust --skip-tasks --skip-answered

If you initialized the project from a non-default branch, you must add --vcs-ref branch-name also to the update commands.

When updating, Copier will do its best to respect the project evolution by using the answers provided last time. However, sometimes this is impossible and conflicts occur. They will be inlined into the conflicting files and can be resolved just like any other git conflict.

For more on updating see copier´s documentation.