SPIKE: Learn Gitea/DCS API that applies to creating releases

[mandolyte]

Include documentation and a step by step manual solution. What will the interaction with Gitea look like for this?

[birchamp]

Abel may have some insight on this.

[mandolyte]

Swagger for QA: https://qa.door43.org/api/swagger#

To see all the releases: https://qa.door43.org/api/swagger#/repository/repoListReleases:

[mandolyte]

AP to create a release is described here:
https://qa.door43.org/api/swagger#/repository/repoCreateRelease

This is a POST, taking 2 parameters and a JSON body.

• The two parameters are owner and repo. For example: es-419_gl and es-419_tn.
• The body JSON looks like this:

{
  "body": "string",
  "draft": true,
  "name": "string",
  "prerelease": true,
  "tag_name": "string",
  "target_commitish": "string"
}

[mandolyte]

Detailed docs at the Gitea page here

{
  "tag_name": "v1.0.0",
  "target_commitish": "master",
  "name": "v1.0.0",
  "body": "Description of the release",
  "draft": false,
  "prerelease": false
}

[mandolyte]

Currently in QA DCS, there are no releases for es-419_gl/es-419_tn:

[mandolyte]

Let's make an example JSON and try it out:

{
  "tag_name": "v1.0.0",
  "target_commitish": "master",
  "name": "v1.0.0",
  "body": "First release of es-419 Translation Notes",
  "draft": false,
  "prerelease": false
}

Code was 201 (success).

Returned JSON:

{
  "id": 852312,
  "tag_name": "v1.0.0",
  "target_commitish": "master",
  "name": "v1.0.0",
  "body": "First release of es-419 Translation Notes",
  "url": "https://qa.door43.org/api/v1/repos/Es-419_gl/es-419_tn/releases/852312",
  "html_url": "https://qa.door43.org/Es-419_gl/es-419_tn/releases/tag/v1.0.0",
  "tarball_url": "https://qa.door43.org/Es-419_gl/es-419_tn/archive/v1.0.0.tar.gz",
  "zipball_url": "https://qa.door43.org/Es-419_gl/es-419_tn/archive/v1.0.0.zip",
  "draft": false,
  "prerelease": false,
  "created_at": "2022-03-11T16:44:09Z",
  "published_at": "2022-03-11T16:44:09Z",
  "author": {
    "id": 13993,
    "login": "cecil.new",
    "full_name": "",
    "email": "[email protected]",
    "avatar_url": "https://qa.door43.org/avatars/4906b5e03f108264e4c119874ce31c37",
    "language": "",
    "is_admin": false,
    "last_login": "0001-01-01T00:00:00Z",
    "created": "2019-09-19T13:37:42Z",
    "repo_languages": null,
    "repo_subjects": null,
    "restricted": false,
    "active": false,
    "prohibit_login": false,
    "location": "",
    "website": "",
    "description": "",
    "visibility": "public",
    "followers_count": 0,
    "following_count": 0,
    "starred_repos_count": 0,
    "username": "cecil.new"
  },
  "assets": []
}

And results on DCS:

[richmahn]

Just remember, a release is a Gitea thing, but our DCS server code will put that release into the Catalog IF (and only if, the only thing that is validated) the manifest.yaml file is valid, as it is in your example ("Catalog (prod)" badge on your release). If it isn't, the release will still be made, and you'll still get the same response when you make it, but will not have a Catalog entry (Invalid badge by the release).

If you are making the release from the master branch, one way to verify that making a release will also result in a Catalog entry is if the master branch itself is in the catalog (all master branches have a catalog entry where stage=latest). So if https://qa.door43.org/api/catalog/v5/entry/es-419_gl/es-419_tn/master doesn't return a 500 error, you are good to go on making a release from master that will appear in the catalog. Hope that makes sense.

Example of bad master branch (no stage=latest for this repo!): https://qa.door43.org/api/catalog/v5/entry/richmahn/en_tn/master

Example of good master branch (has a stage=latest stage): https://qa.door43.org/api/catalog/v5/entry/unfoldingWord/en_tn/master

[mandolyte]

@richmahn
To summarize...

• I can create a release as I've already shown
• tX will add to the release all the assets
• I should only create a release if the manifest is valid, else tX will not create the assets
• I can determine whether the manifest is valid using the simple GET you show above against the master branch (500 error means invalid; else OK)

Give the above, I think it would be nice to show why the manifest is invalid. Could you expose an endpoint for this? I'll file an enhancement request to put this on the table for you.

Feature requested at unfoldingWord/dcs#336

[mandolyte]

@richmahn @birchamp
For further clarification...

1. What are the assets that tX adds to the release? And are these the ones that GLs need?
2. Will the tX pipleline create the assets for all resource types? Those are enumerated below and are the ones in play at this time (2022-03-14 ~ π day!!)

List of Scripture resource types:

• GLT/ULT
• GST/UST
• TN
• TWL
• TW
• TA
• TQ
• SQ
• SN

List of OBS resource types:

• OBS
• obs-tn
• obs-twl
• obs-tq
• obs-sn
• obs-sq