You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Note that the mapping is often not 1-to-1. For example, CITATION.cff allows rich
150
162
specification of author contact information and complex names. In contrast,
151
163
poetry only supports a simple string with a name and email (like in git commits)
@@ -154,6 +166,13 @@ than just move or rename fields**. This means that giving a clean and complete
154
166
mapping overview is not feasible. In case of doubt or confusion, please open an
155
167
issue or consult the `somesy` code.
156
168
169
+
**people** and **entities** are mapped to authors/maintainers/contributors depending
170
+
on the output format. Both fields are marked as necessary but what `somesy` need is an
171
+
author either in **people** or **entities**.
172
+
173
+
When an **entity** has a `ror id` but no `website` set, url related fields will be
174
+
filled with `ror id`.
175
+
157
176
## The somesy CLI tool
158
177
159
178
You can see all supported somesy CLI command options using `somesy --help`:
@@ -168,13 +187,13 @@ defaults, while options passed as CLI arguments override the configuration.
168
187
169
188
Without an input file specifically provided, somesy will check if it can find a valid
170
189
171
-
*`.somesy.toml`
172
-
*`somesy.toml`
173
-
*`pyproject.toml` (in `tool.somesy` section)
174
-
*`Project.toml` (in `tool.somesy` section)
175
-
*`fpm.toml` (in `tool.somesy` section)
176
-
*`package.json` (in `somesy` section)
177
-
*`Cargo.toml` (in `package.metadata.somesy` section)
190
+
-`.somesy.toml`
191
+
-`somesy.toml`
192
+
-`pyproject.toml` (in `tool.somesy` section)
193
+
-`Project.toml` (in `tool.somesy` section)
194
+
-`fpm.toml` (in `tool.somesy` section)
195
+
-`package.json` (in `somesy` section)
196
+
-`Cargo.toml` (in `package.metadata.somesy` section)
178
197
179
198
which is located in the current working directory. If you want to provide
180
199
the somesy input file from a different location, you can pass it with the `-i` option.
@@ -221,15 +240,23 @@ one of the supported input formats:
221
240
email = "a.contributor@example.com"
222
241
orcid = "https://orcid.org/0000-0000-0000-0002"
223
242
243
+
# add an organization as a maintainer
244
+
[[tool.somesy.project.entities]]
245
+
name = "My Super Organization"
246
+
email = "info@my-super-org.com"
247
+
website = "https://my-super-org.com"
248
+
rorid = "https://ror.org/02nv7yv05" # highly recommended set a ror id for your organization
249
+
224
250
[tool.somesy.config]
225
251
verbose = true # show detailed information about what somesy is doing
226
252
```
227
253
228
254
=== "Project.toml"
229
-
```toml
230
-
name = "my-amazing-project"
231
-
version = "0.1.0"
232
-
uuid = "c7e460c6-3f3e-11ec-8d3d-0242ac130003"
255
+
256
+
````toml
257
+
name = "my-amazing-project"
258
+
version = "0.1.0"
259
+
uuid = "c7e460c6-3f3e-11ec-8d3d-0242ac130003"
233
260
234
261
[deps]
235
262
...
@@ -259,14 +286,21 @@ one of the supported input formats:
259
286
email = "a.contributor@example.com"
260
287
orcid = "https://orcid.org/0000-0000-0000-0002"
261
288
289
+
# add an organization as a maintainer
290
+
[[tool.somesy.project.entities]]
291
+
name = "My Super Organization"
292
+
email = "info@my-super-org.com"
293
+
website = "https://my-super-org.com"
294
+
rorid = "https://ror.org/02nv7yv05"# highly recommended set a ror id for your organization
295
+
262
296
[tool.somesy.config]
263
297
verbose = true# show detailed information about what somesy is doing
264
298
```
265
299
266
300
=== "fpm.toml"
267
-
```toml
268
-
name = "my-amazing-project"
269
-
version = "0.1.0"
301
+
```toml
302
+
name = "my-amazing-project"
303
+
version = "0.1.0"
270
304
271
305
[tool.somesy.project]
272
306
name = "my-amazing-project"
@@ -293,6 +327,13 @@ one of the supported input formats:
293
327
email = "a.contributor@example.com"
294
328
orcid = "https://orcid.org/0000-0000-0000-0002"
295
329
330
+
# add an organization as a maintainer
331
+
[[tool.somesy.project.entities]]
332
+
name = "My Super Organization"
333
+
email = "info@my-super-org.com"
334
+
website = "https://my-super-org.com"
335
+
rorid = "https://ror.org/02nv7yv05"# highly recommended set a ror id for your organization
336
+
296
337
[tool.somesy.config]
297
338
verbose = true# show detailed information about what somesy is doing
298
339
```
@@ -330,6 +371,14 @@ one of the supported input formats:
330
371
}
331
372
]
332
373
},
374
+
"entities":[
375
+
{
376
+
"name": "My Super Organization",
377
+
"email": "info@my-super-org.com",
378
+
"website": "https://my-super-org.com",
379
+
"rorid": "https://ror.org/02nv7yv05"
380
+
}
381
+
],
333
382
"config": {
334
383
"verbose": true
335
384
}
@@ -453,6 +502,46 @@ after running somesy (to remove the duplicate entries with the incorrect ORCID).
453
502
454
503
Person identification and merging is not applied to standards with free text fields for authors or maintainers, such as `fpm.toml`.
455
504
505
+
When somesy compares two metadata records about an entity, it will proceed as follows:
506
+
507
+
1. If both records contain a ROR ID, then the entity is the same if the ROR IDs are equal, and different if they are not.
508
+
2. Otherwise, if both records contain a website URL, and it is the same URL, then they are the same entity.
509
+
3. Otherwise, if both records have an attached email address, and it is the same email, then they are the same entity.
510
+
4. Otherwise, the records are considered to be about the same entity if they agree on the name.
511
+
512
+
!!! tip
513
+
514
+
State ROR IDs for entities whenever possible to ensure reliable identification!
515
+
516
+
!!! tip
517
+
518
+
If a ROR ID is not available, state website URLs for entities to help with identification!
519
+
520
+
Somesy will usually correctly understand cases such as:
521
+
522
+
1. A ROR ID being added to an entity (i.e. if it was not present before)
523
+
2. A website URL being added to an entity (if no ROR ID is present)
524
+
3. A changed email address (if the name stays the same)
525
+
4. A changed name (if the email address stays the same)
526
+
5. Any other relevant metadata attached to the entity
527
+
528
+
Nevertheless, you should **check the changes somesy does** before committing them to your repository,
529
+
especially **after you significantly modified your project metadata**.
530
+
531
+
!!! warning
532
+
533
+
Note that changing the ROR ID will not be recognized,
534
+
because ROR IDs are assumed to be unique per entity.
535
+
536
+
If you initially have stated an incorrect ROR ID for an entity and then change it, **somesy will think that this is a new entity**.
537
+
Therefore, **in such a case you will need to fix the ROR ID in all configured somesy targets** either
538
+
before running somesy (so somesy will not create new entity entries), or
539
+
after running somesy (to remove the duplicate entries with the incorrect ROR ID).
540
+
541
+
!!! warning
542
+
543
+
Entity identification and merging is not applied to standards with free text fields for entities, such as `fpm.toml`.
544
+
456
545
### Codemeta
457
546
458
547
While `somesy` is modifying existing files for most supported formats and implements
@@ -493,17 +582,13 @@ file in the somesy repository, which is also shown as the
493
582
494
583
```shell
495
584
somesy fill docs/_template_authors.md -o AUTHORS.md
496
-
```
585
+
````
497
586
498
-
??? example "_template_authors.md"
499
-
```
500
-
--8<-- "docs/_template_authors.md"
501
-
```
587
+
??? example "\_template_authors.md"
588
+
`--8<-- "docs/_template_authors.md"`
502
589
503
590
??? example "AUTHORS.md"
504
-
```
505
-
--8<-- "AUTHORS.md"
506
-
```
591
+
`--8<-- "AUTHORS.md"`
507
592
508
593
The template gets the complete
509
594
[ProjectMetadata](reference/somesy/core/models.md#somesy.core.models.ProjectMetadata) as its context, so it is possible to access all included project and contributor information.
0 commit comments