User Manual¶
This is the reference manual for somesy providing details about its
configuration and behavior.
Before you proceed, make sure you have read the introduction and the quick-start guide.
Somesy Metadata Schemas¶
Because the same information is represented in different ways and more or less detail in different files, somesy requires to put all project information in a somesy-specific input section is located in a supported input file. Somesy will use this as the single source of truth for the supported project metadata fields and can synchronize this information into different target files.
Info
The somesy schemas are designed to allow expressing metadata in the most useful and rich form, i.e. the best form that some of the target formats supports.
Somesy project metadata consists of two main schemas - one schema for describing people (authors, maintainers, contributors), and a schema describing the project.
The somesy metadata fields (especially for people) are mostly based on
Citation File Format 1.2, with some custom extensions.
Somesy will try staying aligned with future revisions of CITATION.cff, unless
for technical or practical reasons a deviation or extension is justified.
One useful distinction somesy does in contrast to many target formats is to allow stating all people in one place. If a person is both an author and a maintainer, that person does not need to be listed with all information twice.
This is done by adding the author and maintainer flags that can be set for
every listed person. Somesy will take care of duplicating the entries where this
is needed.
Furthermore somesy allows to provide more fine-grained information about the
contribution of a person and acknowledge contributors that are neither full
authors or maintainers.
Note
Currently, provided information about contributors that are neither authors nor maintainers, and all the detailed information on the contributions is not used.
Nevertheless, we encourage tracking granular contributor and contribution information in order to motivate and acknowledge also minor or invisible contributions to a projects.
Once CITATION.cff introduces corresponding mechanisms,
somesy will be aligned with the corresponding capabilities.
Furthermore, somesy might support the
allcontributors tool as a target in the future.
Schemas Overview¶
Here is an overview of the schemas used in somesy.
The complete somesy input file (somesy.toml) or section (pyproject.toml).
| Field | Type | Required? | Default | Description |
|---|---|---|---|---|
| project | ProjectMetadata | yes | Project metadata to be used and synchronized. | |
| config | SomesyConfig | no | somesy tool configuration (matches CLI flags). |
Pydantic model for Project Metadata Input.
| Field | Type | Required? | Default | Description |
|---|---|---|---|---|
| name | str | yes | Project name. | |
| description | str | yes | Project description. | |
| version | str | no | Project version. | |
| license | LicenseEnum | yes | SPDX License string. | |
| homepage | Annotated | no | URL of the project homepage. | |
| repository | Annotated | no | URL of the project source code repository. | |
| documentation | Annotated | no | URL of the project documentation. | |
| keywords | List[str] | no | Keywords that describe the project. | |
| people | List[Person] | no | Project authors, maintainers and contributors. | |
| entities | List[Entity] | no | Project authors, maintainers and contributors as entities (organizations). |
Metadata about a person in the context of a software project.
This schema is based on CITATION.cff 1.2, modified and extended for the needs of somesy.
| Field | Type | Required? | Default | Description |
|---|---|---|---|---|
| str | no | The person's email address. | ||
| alias | str | no | The contributor's alias. | |
| address | str | no | The contributor's address. | |
| city | str | no | The entity's city. | |
| country | Country | no | The entity's country. | |
| fax | str | no | The person's fax number. | |
| post_code | str | no | The entity's post-code. | |
| region | str | no | The entity's region. | |
| tel | str | no | The entity's phone number. | |
| author | bool | no | false | Indicates whether the entity is an author of the project (i.e. significant contributor). |
| publication_author | bool | no | Indicates whether the entity is to be listed as an author in academic citations. | |
| maintainer | bool | no | false | Indicates whether the entity is a maintainer of the project (i.e. for contact). |
| contribution | str | no | Summary of how the entity contributed to the project. | |
| contribution_types | List[ContributionTypeEnum] | no | Relevant types of contributions (see https://allcontributors.org/docs/de/emoji-key). | |
| contribution_begin | date | no | Beginning date of the contribution. | |
| contribution_end | date | no | Ending date of the contribution. | |
| orcid | Annotated | no | The person's ORCID url (not required, but highly suggested). | |
| family_names | str | yes | The person's family names. | |
| given_names | str | yes | The person's given names. | |
| name_particle | str | no | The person's name particle, e.g., a nobiliary particle or a preposition meaning 'of' or 'from' (for example 'von' in 'Alexander von Humboldt'). | |
| name_suffix | str | no | The person's name-suffix, e.g. 'Jr.' for Sammy Davis Jr. or 'III' for Frank Edwin Wright III. | |
| affiliation | str | no | The person's affiliation. |
Metadata about an entity in the context of a software project ownership.
An entity, i.e., an institution, team, research group, company, conference, etc., as opposed to a single natural person. This schema is based on CITATION.cff 1.2, modified and extended for the needs of somesy.
| Field | Type | Required? | Default | Description |
|---|---|---|---|---|
| str | no | The person's email address. | ||
| alias | str | no | The contributor's alias. | |
| address | str | no | The contributor's address. | |
| city | str | no | The entity's city. | |
| country | Country | no | The entity's country. | |
| fax | str | no | The person's fax number. | |
| post_code | str | no | The entity's post-code. | |
| region | str | no | The entity's region. | |
| tel | str | no | The entity's phone number. | |
| author | bool | no | false | Indicates whether the entity is an author of the project (i.e. significant contributor). |
| publication_author | bool | no | Indicates whether the entity is to be listed as an author in academic citations. | |
| maintainer | bool | no | false | Indicates whether the entity is a maintainer of the project (i.e. for contact). |
| contribution | str | no | Summary of how the entity contributed to the project. | |
| contribution_types | List[ContributionTypeEnum] | no | Relevant types of contributions (see https://allcontributors.org/docs/de/emoji-key). | |
| contribution_begin | date | no | Beginning date of the contribution. | |
| contribution_end | date | no | Ending date of the contribution. | |
| date_end | date | no | The entity's ending date, e.g., when the entity is a conference. | |
| date_start | date | no | The entity's starting date, e.g., when the entity is a conference. | |
| location | str | no | The entity's location, e.g., when the entity is a conference. | |
| name | str | yes | The entity's name. | |
| website | Annotated | no | The entity's website. | |
| rorid | Annotated | no | The entity's ROR ID url (not required, but highly suggested). |
Pydantic model for somesy tool configuration.
Note that all fields match CLI options, and CLI options will override the
values declared in a somesy input file (such as somesy.toml).
| Field | Type | Required? | Default | Description |
|---|---|---|---|---|
| show_info | bool | no | false | Show basic information messages on run (-v flag). |
| verbose | bool | no | false | Show verbose messages on run (-vv flag). |
| debug | bool | no | false | Show debug messages on run (-vvv flag). |
| input_file | Path | no | "somesy.toml" | Project metadata input file path. |
| no_sync_pyproject | bool | no | false | Do not sync with pyproject.toml. |
| pyproject_file | Path / List[Path] | no | "pyproject.toml" | pyproject.toml file path. |
| no_sync_package_json | bool | no | false | Do not sync with package.json. |
| package_json_file | Path / List[Path] | no | "package.json" | package.json file path. |
| no_sync_julia | bool | no | false | Do not sync with Project.toml. |
| julia_file | Path / List[Path] | no | "Project.toml" | Project.toml file path. |
| no_sync_fortran | bool | no | false | Do not sync with fpm.toml. |
| fortran_file | Path / List[Path] | no | "fpm.toml" | fpm.toml file path. |
| no_sync_pom_xml | bool | no | false | Do not sync with pom.xml. |
| pom_xml_file | Path / List[Path] | no | "pom.xml" | pom.xml file path. |
| no_sync_mkdocs | bool | no | false | Do not sync with mkdocs.yml. |
| mkdocs_file | Path / List[Path] | no | "mkdocs.yml" | mkdocs.yml file path. |
| no_sync_rust | bool | no | false | Do not sync with Cargo.toml. |
| rust_file | Path / List[Path] | no | "Cargo.toml" | Cargo.toml file path. |
| no_sync_cff | bool | no | false | Do not sync with CFF. |
| cff_file | Path / List[Path] | no | "CITATION.cff" | CFF file path. |
| no_sync_codemeta | bool | no | false | Do not sync with codemeta.json. |
| codemeta_file | Path / List[Path] | no | "codemeta.json" | codemeta.json file path. |
| merge_codemeta | bool | no | false | Merge codemeta.json with with an existing codemeta.json file. |
| pass_validation | bool | no | false | Pass validation for all output files. |
| packages | Path / List[Path] | no | Packages (sub-folders) for monorepos with their own somesy config. |
Metadata Mapping¶
From its own schema somesy must convert the information into the target formats.
The following tables sketch how fields are mapped to corresponding other fields in
some of the currently supported formats. Bold field names are mandatory, the others are optional.
| Somesy Field | Poetry Config | SetupTools Config | Java POM | Julia Config | Fortran Config | package.json | mkdocs.yml | Rust Config | CITATION.cff | CodeMeta |
|---|---|---|---|---|---|---|---|---|---|---|
| given-names | name(+email) | name | name | name(+email) | name(+email) | name | name(+email) | name(+email) | givenName | name(+email) |
| family-names | name(+email) | name | name | name(+email) | name(+email) | name | name(+email) | name(+email) | familyName | name(+email) |
| name(+email) | name(+email) | name(+email) | name(+email) | name(+email) | name(+email) | |||||
| orcid | - | - | url | - | - | url | - | - | id | - |
| (many others) | - | - | - | - | - | - | - | - | (same) | - |
| Somesy Field | Poetry Config | SetupTools Config | Java POM | Julia Config | Fortran Config | package.json | mkdocs.yml | Rust Config | CITATION.cff | CodeMeta |
|---|---|---|---|---|---|---|---|---|---|---|
| name | name(+email) | name | name | name(+email) | name(+email) | name | name(+email) | name(+email) | givenName | name(+email) |
| name(+email) | name(+email) | name(+email) | name(+email) | name(+email) | name(+email) | |||||
| rorid | - | - | url | - | - | url | - | - | id | - |
| website | - | - | url | - | - | url | - | - | id | - |
| (many others) | - | - | - | - | - | - | - | - | (same) | - |
| Somesy Field | Poetry Config | SetupTools Config | Java POM | Julia Config | Fortran Config | package.json | mkdocs.yml | Rust Config | CITATION.cff | CodeMeta |
|---|---|---|---|---|---|---|---|---|---|---|
| name | name | name | name | name | name | name | site_name | name | title | name |
| description | description | description | description | - | description | description | site_description | description | abstract | description |
| license | license | license | licenses.license | - | license | license | - | license | license | license |
| version | version | version | version | version | version | version | - | version | version | version |
| author=true | authors | authors | developers | authors | author | author | site_author | authors | authors | author |
| maintainer=true | maintainers | maintainers | - | - | maintainer | maintainers | - | - | contact | maintainer |
| people | - | - | - | - | - | contributors | - | - | - | contributor |
| entities | - | - | - | - | - | contributors | - | - | - | contributor |
| keywords | keywords | keywords | - | - | keywords | keywords | - | keywords | keywords | keywords |
| homepage | homepage | urls.homepage | urls | - | homepage | homepage | site_url | homepage | url | url |
| repository | repository | urls.repository | scm.url | - | - | repository | repo_url | repository | repository_code | codeRepository |
| documentation | documentation | urls.documentation | distributionManagement.site.url | - | - | - | - | documentation | - | buildInstructions |
Note that the mapping is often not 1-to-1. For example, CITATION.cff allows rich
specification of author contact information and complex names. In contrast,
poetry only supports a simple string with a name and email (like in git commits)
to list authors and maintainers. Therefore somesy sometimes must do much more
than just move or rename fields. This means that giving a clean and complete
mapping overview is not feasible. In case of doubt or confusion, please open an
issue or consult the somesy code.
people and entities are mapped to authors/maintainers/contributors depending
on the output format. Both fields are marked as necessary but what somesy need is an
author either in people or entities.
When an entity has a ror id but no website set, url related fields will be
filled with ror id.
The somesy CLI tool¶
You can see all supported somesy CLI command options using somesy --help:
somesy sync --help
Usage: somesy sync [OPTIONS] COMMAND [ARGS]...
Sync project metadata input with metadata files.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --input-file -i FILE Somesy input file path │
│ (default: .somesy.toml) │
│ [default: None] │
│ --no-sync-pyproject -P Do not sync pyproject.toml │
│ file (default: False) │
│ --pyproject-file -p FILE Existing pyproject.toml │
│ file path(s) (default: │
│ pyproject.toml) │
│ [default: None] │
│ --no-sync-package-json -J Do not sync package.json │
│ file (default: False) │
│ --package-json-file -j FILE Existing package.json file │
│ path(s) (default: │
│ package.json) │
│ [default: None] │
│ --no-sync-julia -L Do not sync Project.toml │
│ (Julia) file (default: │
│ False) │
│ --julia-file -l FILE Custom Project.toml (Julia) │
│ file path(s) (default: │
│ Project.toml) │
│ [default: None] │
│ --no-sync-fortran -F Do not sync fpm.toml │
│ (Fortran) file (default: │
│ False) │
│ --fortran-file -f FILE Custom fpm.toml (Fortran) │
│ file path(s) (default: │
│ fpm.toml) │
│ [default: None] │
│ --no-sync-pomxml -X Do not sync pom.xml (Java │
│ Maven) file (default: │
│ False) │
│ --pomxml-file -x FILE Custom pom.xml (Java Maven) │
│ file path(s) (default: │
│ pom.xml) │
│ [default: None] │
│ --no-sync-mkdocs -D Do not sync mkdocs.yml file │
│ (default: False) │
│ --mkdocs-file -d FILE Custom mkdocs.yml file │
│ path(s) (default: │
│ mkdocs.yml) │
│ [default: None] │
│ --no-sync-rust -R Do not sync Cargo.toml file │
│ (default: False) │
│ --rust-file -r FILE Custom Cargo.toml file │
│ path(s) (default: │
│ Cargo.toml) │
│ [default: None] │
│ --no-sync-cff -C Do not sync CITATION.cff │
│ file (default: False) │
│ --cff-file -c FILE CITATION.cff file path(s) │
│ (default: CITATION.cff) │
│ [default: None] │
│ --no-sync-codemeta -M Do not sync codemeta.json │
│ file (default: False) │
│ --codemeta-file -m FILE Custom codemeta.json file │
│ path(s) (default: │
│ codemeta.json) │
│ [default: None] │
│ --merge --overwrite Merge codemeta.json with │
│ with an existing │
│ codemeta.json file │
│ (default: False) │
│ [default: overwrite] │
│ --pass-validation -P Pass validation of metadata │
│ files (default: False) │
│ --packages -k FILE Packages (subfolders) for │
│ monorepos with their own │
│ somesy config. │
│ [default: None] │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
Everything that can be configured as a CLI flag can also be set in a somesy.toml file
in the [config] section. CLI arguments set in an input file override the
defaults, while options passed as CLI arguments override the configuration.
Without an input file specifically provided, somesy will check if it can find a valid
.somesy.tomlsomesy.tomlpyproject.toml(intool.somesysection)Project.toml(intool.somesysection)fpm.toml(intool.somesysection)package.json(insomesysection)Cargo.toml(inpackage.metadata.somesysection)
which is located in the current working directory. If you want to provide
the somesy input file from a different location, you can pass it with the -i option.
Somesy Input File¶
Here is an example how project metadata and somesy can be configured using
one of the supported input formats:
[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
# add an organization as a maintainer
[[project.entities]]
name = "My Super Organization"
email = "info@my-super-org.com"
website = "https://my-super-org.com"
rorid = "https://ror.org/02nv7yv05" # highly recommended set a ror id for your organization
[config]
verbose = true # show detailed information about what somesy is doing
[tool.poetry] # [project] in case of poetry version 2
name = "my-amazing-project"
version = "0.1.0"
...
[tool.somesy.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
[[tool.somesy.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 a acknowledged contributor, but not author or maintainer:
[[tool.somesy.project.people]]
given-names = "Another"
family-names = "Contributor"
email = "a.contributor@example.com"
orcid = "https://orcid.org/0000-0000-0000-0002"
# add an organization as a maintainer
[[tool.somesy.project.entities]]
name = "My Super Organization"
email = "info@my-super-org.com"
website = "https://my-super-org.com"
rorid = "https://ror.org/02nv7yv05" # highly recommended set a ror id for your organization
[tool.somesy.config]
verbose = true # show detailed information about what somesy is doing
Support for mono-repos and multi-package projects¶
A research software project might have multiple packages in the root repository. These packages might be in the same or different software languages or frameworks. somesy currently supports synchronizing multiple output files from one somesy project metadata input.
Sync from one somesy input¶
This is the case where you have only one somesy metadata set in your root folder. Output files can be set in the somesy config section.
[project]
...
[config]
pass_validation = true
package_json_file = ['package.json', 'package1/package.json']
pyproject_toml_file = 'package2/pyproject.toml'
Warning
Each output file, such as package.json file, have its required fields and these fields are enforced by somesy. However, in case of mono-repos or multi-package repositories, some of the fields could be omitted, such as version. Therefore, we suggest users to set pass_validation to true if this is the case. somesy will fail otherwise.
The example above shows a project with a package.json file in the root folder and 2 packages in it. Three files are set here so all of them will be updated according to ground truth of somesy project metadata.
Note
Let's remember somesy will create a CITATION.CFF and codemeta.json file in the root folder if it is set otherwise either by cli or by config.
Packages (sub-modules) with their own somesy file¶
A project with multiple packages inside can have completely different metadata such version and authors. Therefore, each package should have a separate metadata, in other words, separate somesy config and project metadata.
[project]
...
[config]
packages = ['package1', 'package2', 'package3']
Each of these packages (sub-folders) are assumed to have separate somesy metadata in the folder. These packages could be a somesy supported language/framework or it could be any other language. somesy will create at least CITATION.CFF and codemeta.json regardless if not instructed otherwise.