{"id":24546798,"url":"https://github.com/materials-data-science-and-informatics/somesy","last_synced_at":"2025-04-15T16:43:19.849Z","repository":{"id":166025369,"uuid":"633289579","full_name":"Materials-Data-Science-and-Informatics/somesy","owner":"Materials-Data-Science-and-Informatics","description":"A CLI tool for synchronizing software project metadata","archived":false,"fork":false,"pushed_at":"2025-03-14T13:03:00.000Z","size":15507,"stargazers_count":13,"open_issues_count":13,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-12T19:51:10.470Z","etag":null,"topics":["fair","metadata"],"latest_commit_sha":null,"homepage":"https://materials-data-science-and-informatics.github.io/somesy/main/","language":"Python","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/Materials-Data-Science-and-Informatics.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS.md","dei":null,"publiccode":null,"codemeta":"codemeta.json","zenodo":null}},"created_at":"2023-04-27T07:23:17.000Z","updated_at":"2025-03-14T12:58:26.000Z","dependencies_parsed_at":"2025-02-05T10:29:52.768Z","dependency_job_id":"44f11983-4c01-4b7f-88c1-a9d6e59e37f6","html_url":"https://github.com/Materials-Data-Science-and-Informatics/somesy","commit_stats":null,"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Materials-Data-Science-and-Informatics%2Fsomesy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Materials-Data-Science-and-Informatics%2Fsomesy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Materials-Data-Science-and-Informatics%2Fsomesy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Materials-Data-Science-and-Informatics%2Fsomesy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Materials-Data-Science-and-Informatics","download_url":"https://codeload.github.com/Materials-Data-Science-and-Informatics/somesy/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249110668,"owners_count":21214376,"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":["fair","metadata"],"created_at":"2025-01-22T22:17:11.472Z","updated_at":"2025-04-15T16:43:19.843Z","avatar_url":"https://github.com/Materials-Data-Science-and-Informatics.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"[\n![Docs](https://img.shields.io/badge/read-docs-success)\n](https://materials-data-science-and-informatics.github.io/somesy)\n[\n![CI](https://img.shields.io/github/actions/workflow/status/Materials-Data-Science-and-Informatics/somesy/ci.yml?branch=main\u0026label=ci)\n](https://github.com/Materials-Data-Science-and-Informatics/somesy/actions/workflows/ci.yml)\n[\n![Test Coverage](https://materials-data-science-and-informatics.github.io/somesy/main/coverage_badge.svg)\n](https://materials-data-science-and-informatics.github.io/somesy/main/coverage)\n[\n![Docs Coverage](https://materials-data-science-and-informatics.github.io/somesy/main/interrogate_badge.svg)\n](https://materials-data-science-and-informatics.github.io/somesy)\n[\n![PyPIPkgVersion](https://img.shields.io/pypi/v/somesy)\n](https://pypi.org/project/somesy/)\n[\n![OpenSSF Best Practices](https://bestpractices.coreinfrastructure.org/projects/7701/badge)\n](https://bestpractices.coreinfrastructure.org/projects/7701)\n[\n![fair-software.eu](https://img.shields.io/badge/fair--software.eu-%E2%97%8F%20%20%E2%97%8F%20%20%E2%97%8F%20%20%E2%97%8F%20%20%E2%97%8F-green)\n](https://fair-software.eu)\n\n\u003c!-- --8\u003c-- [start:abstract] --\u003e\n\n\u003cdiv style=\"text-align: center;\"\u003e\n    \u003cimg alt=\"HMC Logo\" src=\"https://github.com/Materials-Data-Science-and-Informatics/Logos/raw/main/Somesy/Somesy_Logo_Text.png\" style=\"width: 50%; height: 50%;\" /\u003e\n\u003c/div\u003e\n\n# somesy\n\nSomesy (**so**ftware **me**tadata **sy**nc) is a CLI tool to avoid messy software project metadata by keeping it in sync.\n\n## Description\n\nMany development tools either declare or need information about the software project they are used in, such as: the project name, description, version, repository url, license or project authors.\nMost such tools come with configuration files and conventions that are specific to the programming language or chosen technology.\nEmerging best practices for [FAIR](https://www.go-fair.org/fair-principles/) software metadata require to add even _more_ files where such metadata must be stated.\n\nIf good project metadata was a fire-and-forget issue, this would be acceptable, but software is never standing still - maintainers change, contributors come and go, the version number is regularly increased, the project might be moved to a different location.\nProperly maintaining this kind of information in various files scattered around the project is usually _tedious, error-prone and time consuming manual labor_.\n\n**Somesy automates the synchronization of software project metadata and frees your time to focus on your _actual_ work**.\n\n\u003c!-- --8\u003c-- [end:abstract] --\u003e\n\n**You can find more information on configuring, using and contributing to `somesy` in the\n[documentation](https://materials-data-science-and-informatics.github.io/somesy/main).**\n\n\u003c!-- --8\u003c-- [start:quickstart] --\u003e\n\n## Getting Started\n\n### Platform Support\n\nStarting with version **0.3.0**, `somesy` supports Linux, MacOS and Windows.\n\nMake sure that you use the latest version in order to avoid any problems.\n\n! info\n\n    Poetry changed location of its project metadata with its version 2. Starting with version **0.7.0**, `somesy` supports both major versions of `poetry`, version 1 and 2.\n\n### Installing somesy\n\nSomesy requires Python `\u003e=3.8`. To get a first impression, you can install the\nlatest stable version of somesy from PyPI using `pip`:\n\n```bash\npip install somesy\n```\n\n\u003e **Note**\n\u003e\n\u003e If you use somesy as a pre-commit hook, you don't have to install somesy on your PC nor add it as a dependency in your Python project. Pre-commit will handle the installation automatically.\n\n### Configuring somesy\n\nYes, somesy is _another_ tool with its own configuration. However, for your\nproject metadata it is hopefully the last file you need, and the only one you\nhave to think about, `somesy` will take care of the others for you!\n\nTo get started, create a file named `somesy.toml`:\n\n\u003c!-- --8\u003c-- [start:somesytoml] --\u003e\n\n```toml\n[project]\nname = \"my-amazing-project\"\nversion = \"0.1.0\"\ndescription = \"Brief description of my amazing software.\"\n\nkeywords = [\"some\", \"descriptive\", \"keywords\"]\nlicense = \"MIT\"\nrepository = \"https://github.com/username/my-amazing-project\"\n\n# This is you, the proud author of your project:\n[[project.people]]\ngiven-names = \"Jane\"\nfamily-names = \"Doe\"\nemail = \"j.doe@example.com\"\norcid = \"https://orcid.org/0000-0000-0000-0001\"\nauthor = true      # is a full author of the project (i.e. appears in citations)\nmaintainer = true  # currently maintains the project (i.e. is a contact person)\n\n# this person is an acknowledged contributor, but not author or maintainer:\n[[project.people]]\ngiven-names = \"Another\"\nfamily-names = \"Contributor\"\nemail = \"a.contributor@example.com\"\norcid = \"https://orcid.org/0000-0000-0000-0002\"\n# ... but for scientific publications, this contributor should be listed as author:\npublication_author = true\n\n# add an organization as a maintainer\n[[project.entities]]\nname = \"My Super Organization\"\nemail = \"info@my-super-org.com\"\nwebsite = \"https://my-super-org.com\"\nrorid = \"https://ror.org/02nv7yv05\" # highly recommended set a ror id for your organization\n\n[config]\nverbose = true     # show detailed information about what somesy is doing\n```\n\n\u003c!-- --8\u003c-- [end:somesytoml] --\u003e\n\nAs Helmholtz Metadata Collaboration (HMC), our goal is to increase usage of metadata and improve metadata quality. Therefore, some fields in `somesy.toml` are set as required fields. This is to increase rigour and completeness of metadata recorded with `somesy` .\n\nAlternatively, you can also add the somesy configuration to an existing\n`pyproject.toml`, `package.json`, `Project.toml`, or `fpm.toml` file. The somesy [manual](https://materials-data-science-and-informatics.github.io/somesy/main/manual/#somesy-input-file) contains examples showing how to do that.\n\n### Using somesy\n\nOnce somesy is installed and configured, somesy can take over and manage your project metadata.\nNow you can run `somesy` simply by using\n\n```bash\nsomesy sync\n```\n\nThe information in your `somesy.toml` is used as the **primary and\nauthoritative** source for project metadata, which is used to update all\nsupported (and enabled) _target files_. You can find an overview of supported\nformats further below.\n\nBy default, `somesy` will create (if they did not exist) or update `CITATION.cff` and `codemeta.json` files in your repository.\nIf you happen to use\n\n-   `pyproject.toml` (in Python projects),\n-   `package.json` (in JavaScript projects),\n-   `Project.toml` (in Julia projects),\n-   `fpm.toml` (in Fortran projects),\n-   `pom.xml` (in Java projects),\n-   `mkdocs.yml` (in projects using MkDocs),\n-   `Cargo.toml` (in Rust projects)\n\nthen somesy would also update the respective information there.\n\nYou can see call available options with `somesy --help`,\nall of these can also be conveniently set in your `somesy.toml` file.\n\n### Somesy as a pre-commit hook\n\n\u003c!-- --8\u003c-- [start:precommit] --\u003e\n\nWe highly recommend to use `somesy` as a [pre-commit hook](https://pre-commit.com/).\nA pre-commit hook runs on every commit to automatically point out issues or fix them on the spot,\nso if you do not use pre-commit in your project yet, you should start today!\nWhen used this way, `somesy` can fix most typical issues with your project\nmetadata even before your changes can leave your computer.\n\nTo add `somesy` as a pre-commit hook, add it to your `.pre-commit-config.yaml`\nfile in the root folder of your repository:\n\n```yaml\nrepos:\n    # ... (your other hooks) ...\n    - repo: https://github.com/Materials-Data-Science-and-Informatics/somesy\n      rev: 'v0.7.2'\n      hooks:\n          - id: somesy\n```\n\n\u003e **Note**\n\u003e\n\u003e Please add the latest version of Somesy to your project. You can update the version of Somesy in your config file now and later to use the newest versions as they become available.\n\nNote that `pre-commit` gives `somesy` the [staged](https://git-scm.com/book/en/v2/Getting-Started-What-is-Git%3F) version of files,\nso when using `somesy` with pre-commit, keep in mind that\n\n-   if `somesy` changed some files, you need to `git add` them again (and rerun pre-commit)\n-   if you explicitly run `pre-commit`, make sure to `git add` all changed files (just like before a commit)\n\n\u003c!-- --8\u003c-- [end:precommit] --\u003e\n\n## Supported File Formats\n\nHere is an overview of all the currently supported files and formats.\n\n| Input Formats  | Status |     | Target Formats                           | Status |\n| -------------- | ------ | --- | ---------------------------------------- | ------ |\n| (.)somesy.toml | ✓      |     | -                                        | ✓      |\n| pyproject.toml | ✓      |     | pyproject.toml _(setuptools and poetry)_ | ✓(1.)  |\n| package.json   | ✓      |     | package.json _(JavaScript)_              | ✓(2.)  |\n| Project.toml   | ✓      |     | Project.toml _(Julia)_                   | ✓      |\n| fpm.toml       | ✓      |     | fpm.toml _(Fortran)_                     | ✓(3.)  |\n|                | ✓      |     | pom.toml _(Java)_                        | ✓(4.)  |\n| Cargo.toml     | ✓      |     | Cargo.toml _(Rust)_                      | ✓      |\n|                |        |     | mkdocs.yml                               | ✓(5.)  |\n|                |        |     | CITATION.cff                             | ✓      |\n|                |        |     | codemeta.json                            | ✓(6.)  |\n\n**Notes:**\n\n1. note that `somesy` does not support setuptools or poetry _dynamic fields_\n2. `package.json` only supports one author, so `somesy` will pick the _first_ listed author\n3. `fpm.toml` only supports one author and maintainer, so `somesy` will pick the _first_ listed author and maintainer\n4. `pom.xml` has no concept of `maintainers`, but it can have multiple licenses (somesy only supports one main project license)\n5. `mkdocs.yml` is a bit special, as it is not a project file, but a documentation file. `somesy` will only update it if it exists and is enabled in the configuration\n6. For handling `codemeta.json` different options exists: Either (A) `somesy` removes any prior existing `codemata.json` files and re-creates it anew, or (B) `somesy` merges an existing `codemeta.json` with the information handled by `somesy`. See the [user manual](https://materials-data-science-and-informatics.github.io/somesy/main/manual/#codemeta) for additional details about CodeMeta handling.\n\n\u003c!-- --8\u003c-- [end:quickstart] --\u003e\n\n\u003c!-- --8\u003c-- [start:citation] --\u003e\n\n## How to Cite\n\nIf you want to cite this project in your scientific work,\nplease use the [citation file](https://citation-file-format.github.io/)\nin the [repository](https://github.com/Materials-Data-Science-and-Informatics/somesy/blob/main/CITATION.cff).\n\n\u003c!-- --8\u003c-- [end:citation] --\u003e\n\u003c!-- --8\u003c-- [start:acknowledgements] --\u003e\n\n## Acknowledgements\n\nWe kindly thank all\n[authors and contributors](https://materials-data-science-and-informatics.github.io/somesy/latest/credits).\n\n\u003cdiv\u003e\n\u003cimg style=\"vertical-align: middle;\" alt=\"HMC Logo\" src=\"https://github.com/Materials-Data-Science-and-Informatics/Logos/raw/main/HMC/HMC_Logo_M.png\" width=50% height=50% /\u003e\n\u0026nbsp;\u0026nbsp;\n\u003cimg style=\"vertical-align: middle;\" alt=\"FZJ Logo\" src=\"https://github.com/Materials-Data-Science-and-Informatics/Logos/raw/main/FZJ/FZJ.png\" width=30% height=30% /\u003e\n\u003c/div\u003e\n\u003cbr /\u003e\n\nThis project was developed at the Institute for Materials Data Science and Informatics\n(IAS-9) of the Jülich Research Center and funded by the Helmholtz Metadata Collaboration\n(HMC), an incubator-platform of the Helmholtz Association within the framework of the\nInformation and Data Science strategic initiative.\n\n\u003c!-- --8\u003c-- [end:acknowledgements] --\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaterials-data-science-and-informatics%2Fsomesy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaterials-data-science-and-informatics%2Fsomesy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaterials-data-science-and-informatics%2Fsomesy/lists"}