{"id":24355200,"url":"https://github.com/dalito/linkml-project-copier","last_synced_at":"2025-04-15T12:29:05.661Z","repository":{"id":272215626,"uuid":"915838411","full_name":"dalito/linkml-project-copier","owner":"dalito","description":"A copier template for your next LinkML project","archived":false,"fork":false,"pushed_at":"2025-04-05T21:39:59.000Z","size":213,"stargazers_count":1,"open_issues_count":5,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-05T22:24:59.841Z","etag":null,"topics":["copier","linkml","schema","template"],"latest_commit_sha":null,"homepage":"","language":"Jinja","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dalito.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-01-12T23:31:08.000Z","updated_at":"2025-04-05T21:28:27.000Z","dependencies_parsed_at":"2025-01-13T01:37:53.646Z","dependency_job_id":"99a0e2ed-1749-481b-ae4d-4059ed451e57","html_url":"https://github.com/dalito/linkml-project-copier","commit_stats":null,"previous_names":["dalito/linkml-project-copier"],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dalito%2Flinkml-project-copier","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dalito%2Flinkml-project-copier/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dalito%2Flinkml-project-copier/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dalito%2Flinkml-project-copier/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dalito","download_url":"https://codeload.github.com/dalito/linkml-project-copier/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249071505,"owners_count":21207995,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["copier","linkml","schema","template"],"created_at":"2025-01-18T17:29:34.540Z","updated_at":"2025-04-15T12:29:05.654Z","avatar_url":"https://github.com/dalito.png","language":"Jinja","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![DOI](https://zenodo.org/badge/915838411.svg)](https://doi.org/10.5281/zenodo.15163584)\n\n# A Copier Template for LinkML Projects\n\nThis template uses the code-scaffolding tool [copier](https://copier.readthedocs.io/) to create a [LinkML](https://github.com/linkml/linkml) project.\nCopier supports code lifecycle management, allowing you to seamlessly incorporate updates into your project when the template is enhanced.\n\n* Starting from 0.2.x we give up compatibility with the directory layout from\n  [linkml-project-cookiecutter](https://github.com/linkml/linkml-project-cookiecutter/)\n  that we followed initially. This is required to introduce new features\n  and to realise our idea of a cleaner, easier to update linkml project template.\n* Early releases (0.1.x) are backwards compatibility with\n  [linkml-project-cookiecutter](https://github.com/linkml/linkml-project-cookiecutter/)\n  (same directory layout and commands).\n  This facilitates experimenting with the migration of existing cruft/cookiecutter-based projects.\n  Over time the migration is expected to become more difficult as the cookiecutter template evolves.\n  We don't plan to maintain compatible releases beyond v0.1.7.\n\nThe generated project uses [just](https://github.com/casey/just) as preferred command runner, even in the 0.1.x releases.\n\n\u003e The starting point of this template was [linkml-project-cookiecutter](https://github.com/linkml/linkml-project-cookiecutter/)\n\u003e (commit [1094cf2](https://github.com/linkml/linkml-project-cookiecutter/commit/1094cf2ce542028ab0017eaa059dd49cdde81fb5), date 2025-01-10).\n\u003e The code from the [just command runner PR](https://github.com/linkml/linkml-project-cookiecutter/pull/127) was also included\n\u003e (up to commit [3eb2522](https://github.com/linkml/linkml-project-cookiecutter/tree/3eb2522f5baa9e8f27ffb4ae28c0134a42d72c9d)).\n\n## Prerequisites\n\nThe following are required and recommended tools for using this copier template and the LinkML project that it generates.\nThis is all one-time setup, so if you have already done it skip to the [next section](#creating-a-new-project)!\nWe assume that you have full internet access.\n\n* **git / GitHub account**\n\n  Git is the version management system with which this template and your repository are managed. The template also assumes that you\n  use GitHub for hosting your project which implies that you have a GitHub account.\n\n* **Python \u003e= 3.9**\n\n  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.\n\n* **uv**\n\n  uv is a tool to manage Python projects and for managing isolated Python-based applications.\n  You will use it in your generated project to manage dependencies and build distribution files.\n  Install uv by following their [instructions](https://docs.astral.sh/uv/getting-started/installation/)\n\n* **copier**\n\n  Copier is a tool for generating projects based on a template (like this one!).\n  It also allows re-configuring the projects and to keep them updated when the original template changes.\n  To insert dates into the template, copier requires [jinja2_time](https://github.com/hackebrot/jinja2-time) in the copier environment.\n  Install both with `uv tool` by running:\n\n  ```shell\n  uv tool install copier\n  uv tool inject copier jinja2_time\n  ```\n\n* **just**\n\n  The project contains a `justfile` with pre-defined complex commands.\n  To execute these commands you need [just](https://github.com/casey/just) as command runner. Install it by running:\n\n  ```shell\n  uv tool install rust-just\n  ```\n\n## Creating a new project\n\n### Step 1: Generate the project files\n\nTo generate a new LinkML project first create a new empty directory for the project and then run the following:\n\n```shell\ncd path/to/new/directory\ncopier copy --trust https://github.com/dalito/linkml-project-copier .\n```\n\nThe `--trust` option is needed because the template uses the jinja_extension `jinja2_time`.\n\nYou will be prompted a few questions.\nThe 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.\n\nIt is also possible to use non-default branches or specific tags via `--vcs-ref` which is useful when developing the template:\n\n```shell\ncopier copy --trust --vcs-ref branch-name gh:dalito/linkml-project-copier ./path/to/destination\n```\n\n### Step 2: Set up the LinkML project\n\nChange to the folder your generated project is in.\n\nOptionally customize your project if needed:\n\n* pass arguments to linkml generators via 'config.yaml' configuration file;\n* pass supported environment variables via '.env.public' configuration file;\n\nSetup your project\n\n```shell\ncd my-awesome-schema  # using the folder example above\njust setup\n```\n\n### Step 3: Edit the schema\n\nEdit the schema (the .yaml file) in the `src/my_awesome_schema/schema` folder with an editor of your choice.\n\nFor developing consistent, well-formatted schemas, the project provides a [pre-commit](https://pre-commit.com/) configuration for some helpful tools.\nIncluded are [yamllint](https://github.com/adrienverge/yamllint) for consistent formatting of the schema-yaml file,\n[ruff](https://docs.astral.sh/ruff/) for formatting and linting Python code and\nthe spell checkers [codespell](https://github.com/codespell-project/codespell) and [typos](https://github.com/crate-ci/typos). To use this\n\n* install pre-commit with: `uv tool install pre-commit`\n* activate pre-commit in the project by running (at the root of the project): `pre-commit install`\n\nOnce installed pre-commit will perform the checks on every commit and reject a commit if errors are found;\nit will even auto-correct several types of errors.\nYou can also run the pre-configured checks manually with `pre-commit run -a`.\n\n### Step 4: Validate the schema\n\n```shell\njust test\n```\n\nThis commands generates the project artefacts from the schema, runs pytest for the Python datamodel and tests loading all valid \u0026 invalid data examples.\n\nAnother important command to check your schema is\n\n```shell\njust lint\n```\n\nwhich runs the linkML linter on your schema.\n\n### Step 5: Generate documentation locally\n\nLinkML generates schema documentation automatically.\nThe template includes the configuration for generating and publishing the documentation with GitHub whenever you push schema changes to GitHub.\nThe published documentation can be found at a URL like this one:\n`https://{github-user-or-organization}.github.io/{project-name}/`\n\nYou can also preview the documentation locally before pushing to GitHub by running:\n\n```shell\njust testdoc\n```\n\n### Step 6: Create a GitHub project\n\n1. Open [GitHub new project](https://github.com/new) and follow the instructions, being sure to NOT add a `README` or `.gitignore` file\n   (this copier template will add those files for you)\n\n2. Add the remote to your local git repository:\n\n   ```shell\n   git remote add origin https://github.com/{github-user-or-organization}/{project-name}.git\n   git branch -M main\n   git push -u origin main\n   ```\n\n3. Configure your repository for deploying the documentation as GitHub pages\n\n* Under Settings \u003e Actions \u003e General in section \"Workflow Permissions\" mark \"Read repository and packages permission\".\n* Go to \"Actions\" tab, select on the left under Actions \"Deploy docs\", and click the \"Run workflow\" button on the right.\n  Run from main-branch as suggested and verify successful completion.\n* Now go back to Settings \u003e Pages. In section \"Build and Deployment\" select\n  * Under \"Source\": \"Deploy from a branch\"\n  * Under \"Branch\": \"gh-pages\" and \"/ (root)\"\n    * Hint: The \"gh-pages\" branch is created automatically in the first successful run of the \"deploy docs\" workflow.\n\n### Step 7: Register the schema\n\nSee [How to register a schema](https://linkml.io/linkml/faq/contributing.html#how-do-i-register-my-schema)\n\n### Making releases\n\nSee [How to Manage Releases of your LinkML Schema](https://linkml.io/linkml/howtos/manage-releases.html)\n\n## Migrating an existing project to use this template\n\nThis is a rough guide on the required steps.\nFeedback and suggestions for improvement based on your experiences are very welcome.\nThe commands are written to be run at the root of your project.\n\n* Start with a clean state of the existing project (check with `git status`).\n* Create a new branch and activate it:\n\n  ```shell\n  git switch -c migrate-to-copier\n  ```\n\n* Adapt your project and create a copier answers file (`.copier-answers`) by running (this updates to the latest released version):\n\n  ```shell\n  copier copy --trust gh:dalito/linkml-project-copier .\n  ```\n\n  * **Starting from a linkml-project-cookiecutter based project**:\n    You may want to migrate in two steps to reduces the number of changes to review.\n    For the first step, a migration to the 0.1.x-series is suggested,\n    which still has the same directory layout as linkml-project-cookiecutter.\n    The command for migrating to a specific tag/release is:\n\n    ```shell\n    copier copy --trust --vcs-ref v0.1.7 gh:dalito/linkml-project-copier .\n    ```\n\n    Look into the `.cruft.json` file to find out which values you chose when you created your original project.\n    Be sure to enter the same values when answering the copier questions.\n\n* Carefully review the changes that copier made to your project.\n* If you used a cruft/cookiecutter template before, you may delete the cruft file `.cruft.json`.\n* If you are happy, commit all changes to the `migrate-to-copier` branch.\n* To finalise the migration, merge the `migrate-to-copier` branch to your main branch.\n\n## Keeping your project up to date or changing its configuration\n\nCopier allows you to update your project with changes from the template.\nYou can also change the project by providing different answers to the questions than the last time.\n\nTo update your project with changes from the template and to reconfigure your project options, run:\n\n```shell\ncopier update --trust\n```\n\nTo do a pure update without re-configuration run:\n\n```shell\ncopier update --trust --skip-answered\n```\n\nIf you initialized the project from a non-default branch, you must add the git branch name (or tag name) also to the update commands:\n\n```shell\ncopier update --trust --vcs-ref branch-or-tag-name --skip-answered\n```\n\nWhen updating, Copier will do its best to respect the project evolution by using the answers provided last time.\nHowever, sometimes this is impossible and conflicts occur.\nThey will be inlined into the conflicting files and can be resolved just like any other git conflict.\n\nFor more on updating see copier's [documentation](https://copier.readthedocs.io/en/stable/updating/).\n\n### Notes on specific updates\n\n#### From 0.1.x to 0.2.x\n\nThe directory layout has changed a lot with the v0.2.0 release.\nSeries 0.1.x had still the directory layout from linkml-project-cookiecutter.\nFor the update some directories have to be cleaned up.\nSince copier can't do this automatically, you have to do the following steps manually:\n\n* **Before running the update**: Run `just clean` to remove the folder `docs`\n  which was git-ignored in 0.1.x (and linkml-cookiecutter) but will become the main version-managed docs folder in 0.2.x.\n* **After running the update** (before committing): Remove the folder `project/docs`\n  which was also gitignored before v0.2.0 and is of no use for 0.2.0 and later releases.\n\n## Contributors\n\nA big thanks to all [contributors](https://github.com/nfdi4cat/pid4cat-model/graphs/contributors).\n\nMain author:\n\n* David Linke (ORCID: 0000-0002-5898-1820) - Idea, initial setup of repository and current maintainer.\n\n## License\n\nThe code in this repository is distributed under MIT license.\n\n## Acknowledgement\n\n[linkml-project-cookiecutter](https://github.com/linkml/linkml-project-cookiecutter) provided a great basis for starting this new linkml project template.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdalito%2Flinkml-project-copier","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdalito%2Flinkml-project-copier","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdalito%2Flinkml-project-copier/lists"}