Quickstart

Getting Started¶

Platform Support¶

Starting with version 0.3.0, somesy supports Linux, MacOS and Windows.

Make sure that you use the latest version in order to avoid any problems.

Installing somesy¶

Somesy requires Python >=3.8. To get a first impression, you can install the latest stable version of somesy from PyPI using pip:

pip install somesy

Note

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.

Configuring somesy¶

Yes, somesy is another tool with its own configuration. However, for your project metadata it is hopefully the last file you need, and the only one you have to think about, somesy will take care of the others for you!

To get started, create a file named somesy.toml:

[project]
name = "my-amazing-project"
version = "0.1.0"
description = "Brief description of my amazing software."

keywords = ["some", "descriptive", "keywords"]
license = "MIT"
repository = "https://github.com/username/my-amazing-project"

# This is you, the proud author of your project:
[[project.people]]
given-names = "Jane"
family-names = "Doe"
email = "j.doe@example.com"
orcid = "https://orcid.org/0000-0000-0000-0001"
author = true      # is a full author of the project (i.e. appears in citations)
maintainer = true  # currently maintains the project (i.e. is a contact person)

# this person is an acknowledged contributor, but not author or maintainer:
[[project.people]]
given-names = "Another"
family-names = "Contributor"
email = "a.contributor@example.com"
orcid = "https://orcid.org/0000-0000-0000-0002"
# ... but for scientific publications, this contributor should be listed as author:
publication_author = true

[config]
verbose = true     # show detailed information about what somesy is doing

As 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 .

Alternatively, you can also add the somesy configuration to an existing pyproject.toml, package.json, Project.toml, or fpm.toml file. The somesy manual contains examples showing how to do that.

Using somesy¶

Once somesy is installed and configured, somesy can take over and manage your project metadata. Now you can run somesy simply by using

somesy sync

The information in your somesy.toml is used as the primary and authoritative source for project metadata, which is used to update all supported (and enabled) target files. You can find an overview of supported formats further below.

By default, somesy will create (if they did not exist) or update CITATION.cff and codemeta.json files in your repository. If you happen to use

pyproject.toml (in Python projects),
package.json (in JavaScript projects),
Project.toml (in Julia projects),
fpm.toml (in Fortran projects),
pom.xml (in Java projects),
mkdocs.yml (in projects using MkDocs),
Cargo.toml (in Rust projects)

then somesy would also update the respective information there.

You can see call available options with somesy --help, all of these can also be conveniently set in your somesy.toml file.

Somesy as a pre-commit hook¶

We highly recommend to use somesy as a pre-commit hook. A pre-commit hook runs on every commit to automatically point out issues or fix them on the spot, so if you do not use pre-commit in your project yet, you should start today! When used this way, somesy can fix most typical issues with your project metadata even before your changes can leave your computer.

To add somesy as a pre-commit hook, add it to your .pre-commit-config.yaml file in the root folder of your repository:

repos:
  # ... (your other hooks) ...
  - repo: https://github.com/Materials-Data-Science-and-Informatics/somesy
    rev: "v0.5.0"
    hooks:
      - id: somesy

Note

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.

Note that pre-commit gives somesy the staged version of files, so when using somesy with pre-commit, keep in mind that

if somesy changed some files, you need to git add them again (and rerun pre-commit)
if you explicitly run pre-commit, make sure to git add all changed files (just like before a commit)

Supported File Formats¶

Here is an overview of all the currently supported files and formats.

Input Formats	Status	Target Formats	Status
(.)somesy.toml	✓	pyproject.toml (poetry)	✓
pyproject.toml	✓	pyproject.toml (setuptools)	✓(1.)
package.json	✓	package.json (JavaScript)	✓(2.)
Project.toml	✓	Project.toml (Julia)	✓
fpm.toml	✓	fpm.toml (Fortran)	✓(3.)
	✓	pom.toml (Java)	✓(4.)
Cargo.toml	✓	Cargo.toml (Rust)	✓
		mkdocs.yml	✓(5.)
		CITATION.cff	✓
		codemeta.json	✓(6.)

Notes:

note that somesy does not support setuptools dynamic fields
package.json only supports one author, so somesy will pick the first listed author
fpm.toml only supports one author and maintainer, so somesy will pick the first listed author and maintainer
pom.xml has no concept of maintainers, but it can have multiple licenses (somesy only supports one main project license)
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
unlike other targets, somesy will re-create the codemeta.json (i.e. do not edit it by hand!)