From f0f1586a9d3f6617ba63692fc2017bc0a28cd330 Mon Sep 17 00:00:00 2001 From: Michael Hucka Date: Sun, 19 Nov 2023 17:27:34 -0800 Subject: [PATCH] fix: various Markdown lint issues --- README.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 664b1fc..878980f 100644 --- a/README.md +++ b/README.md @@ -223,6 +223,7 @@ No matter whether IGA is run locally on your computer or as a GitHub Actions wor ### Configuring and running IGA locally To send a GitHub release to your InvenioRDM server, IGA needs this information: + 1. (Required) The identity of the GitHub release to be archived 2. (Required) The address of the destination InvenioRDM server 3. (Required) A personal access token for InvenioRDM (from [above](#getting-an-inveniordm-token)) @@ -295,10 +296,11 @@ Note that when you run IGA as a GitHub Actions workflow, you do not need to crea ### Specifying a GitHub release A GitHub release can be specified to IGA in one of two mutually-exclusive ways: - 1. The full URL of the web page on GitHub of a tagged release. In this case, + +1. The full URL of the web page on GitHub of a tagged release. In this case, the URL must be the final argument on the command line invocation of IGA and the options `--account` and `--repo` must be omitted. - 2. A combination of _account name_, _repository name_, and _tag_. In this +2. A combination of _account name_, _repository name_, and _tag_. In this case, the final argument on the command line must be the _tag_, and in addition, values for the options `--account` and `--repo` must be provided. @@ -355,7 +357,8 @@ If the `--community` option is not used, then by default, IGA will finalize and ### Versioning records The option `--parent-record` can be used to indicate that the record being constructed is a new version of an existing record. This will make IGA use the InvenioRDM API for [record versioning](https://inveniordm.docs.cern.ch/releases/versions/version-v2.0.0/#versioning-support). The newly-created record will be linked to a parent record identified by the value passed to `--parent-record`. The value must be either an InvenioRDM record identifier (which is a sequence of alphanumeric characters of the form _XXXXX-XXXXX_, such as `bknz4-bch35`, generated by the InvenioRDM server), or a URL to the landing page of the record in the InvenioRDM server. (Note that such URLs end in the record identifier.) Here is an example of using this option: -``` + +```shell iga --parent-record xbcd4-efgh5 https://github.com/mhucka/taupe/releases/tag/v1.2.0 ``` @@ -427,6 +430,7 @@ This program exits with a return status code of 0 if no problem is encountered. ## Known issues and limitations The following are known issues and limitations. + * As of mid-2023, InvenioRDM requires names of record creators and other contributors to be split into given (first) and family (surname). This is problematic for multiple reasons. The first is that mononyms are common in many countries: a person's name may legitimately be only a single word which is not conceptually a "given" or "family" name. To compound the difficulty for IGA, names are stored as single fields in GitHub account metadata, so unless a repository has a `codemeta.json` or `CITATION.cff` file (which allow authors more control over how they want their names represented), IGA is forced to try to split the single GitHub name string into two parts. _A foolproof algorithm for doing this does not exist_, so IGA will sometimes get it wrong. (That said, IGA goes to extraordinary lengths to try to do a good job.) * InvenioRDM requires that identities (creators, contributors, etc.) to be labeled as personal or organizational. The nature of identities is usually made clear in `codemeta.json` and `CITATION.cff` files. GitHub also provides a flag that is meant to be used to label organizational accounts, but sometimes people don't set the GitHub account information correctly. Consequently, if IGA has to use GitHub data to get (e.g.) the list of contributors on a project, it may mislabel identities in the InvenioRDM record it produces. * Some accounts on GitHub are software automation or "bot" accounts, but are not labeled as such. These accounts are generally indistinguishable from human accounts on GitHub, so if they're not labeled as bot or organizational accounts in GitHub, IGA can't recognize that they're humans. If such an account is the creator of a release in GitHub, and IGA tries to use its name-splitting algorithm on the name of the account, it may produce a nonsensical result. For example, it might turn "Travis CI" into an entry with a first name of "Travis" and last name of "CI". @@ -478,7 +482,7 @@ IGA uses multiple other open-source packages, without which it would have taken * [nameparser](https://github.com/derek73/python-nameparser) – package for parsing human names into their individual components * [probablepeople](https://github.com/datamade/probablepeople) – package for parsing names into components using ML-based techniques * [pybtex](https://pybtex.org) – BibTeX parser and formatter -* [pybtex-apa7-style]() – plugin for [pybtex](https://pybtex.org) that provides APA7 style formatting +* [pybtex-apa7-style](https://pypi.org/project/pybtex-apa7-style/) – plugin for [pybtex](https://pybtex.org) that provides APA7 style formatting * [pymdown-extensions](https://github.com/facelessuser/pymdown-extensions) – extensions for Python Markdown * [pytest](https://docs.pytest.org/en/stable/) – testing framework * [pytest-cov](https://github.com/pytest-dev/pytest-cov) – coverage reports for use with `pytest`