Create and publish a V0.0.1 document release

[axel-h]

Now that #112 has been merged, there should be a first release of the document with the goal to have this also on the RISC-V docs website https://lf-riscv.atlassian.net/wiki/spaces/HOME/pages/16154769/RISC-V+Technical+Specifications#Non-ISA-Specifications. Could still be marked as draft or prerelease.

[wmat]

Is this manual an artificate under the toolchain TG?

[apazos]

@axel-h , we discussed your CI workflow request at the last Toolchain SIG meeting on 11/21 and we agreed on adding a CI workflow, but not an official release yet.

In addition, the spec versioning scheme will change with the new BoD Policy, we should wait until it is settled.

Can you explain your urgency to have a first release?

Adding @cmuellner to comment as well.

[axel-h]

There is no urgency, it would just be nice to have something one can refer to in other document - besides just a commit ID in a repository.

[axel-h]

It seems merging the workflow was not enough, this also needs a workflow approval somewhere. The CI job
https://github.com/riscv-non-isa/riscv-asm-manual/actions/runs/12198852957/job/34031552715 tried to upload the artifacts after a push to main to https://github.com/riscv-non-isa/riscv-asm-manual/releases/tag/untagged-b05b87e58d03d44b1e68, but this gives a 404 and the draft documents for latest maindo not show up under https://github.com/riscv-non-isa/riscv-asm-manual/releases. It workes in my fork at https://github.com/axel-h/riscv-asm-manual/releases when testing this. Could you have a look at "Settings" -> "Actions" -> ""General" -> "Workflow permissions", that the GITHUB_TOKEN has read and write access. Default might be just read access.

[wmat]

The permissions for the Action are read/write. The reason the PDF doesn't show up in the releases section on GitHub is because it only uploads as an asset of the Action, not a release. If you would like it to create a draft release on each merge, you need another action setup such as is found in the riscv-isa-manual repo here https://github.com/riscv/riscv-isa-manual/actions/workflows/merge-and-release.yml, if that is something you'd like on this repository you can add the Action or let me know and I can do it. Optionally, you can create a release manually.

…

On Sat, Dec 7, 2024 at 6:59 AM Axel Heider ***@***.***> wrote: It seems merging the workflow was not enough, this also needs a workflow approval somewhere. The CI job https://github.com/riscv-non-isa/riscv-asm-manual/actions/runs/12198852957/job/34031552715 tried to upload the artifacts after a push to main to https://github.com/riscv-non-isa/riscv-asm-manual/releases/tag/untagged-b05b87e58d03d44b1e68, but this gives a 404 and the draft documents for latest maindo not show up under https://github.com/riscv-non-isa/riscv-asm-manual/releases. It workes in my fork at https://github.com/axel-h/riscv-asm-manual/releases when testing this. Could you have a look at "Settings" -> "Actions" -> ""General" -> "Workflow permissions", that the GITHUB_TOKEN has read and write access. Default might be just read access. — Reply to this email directly, view it on GitHub <#115 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAAN6ZFC4PSH3ZWKJLISEJL2ELPJZAVCNFSM6AAAAABTEXS7SWVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDKMRVGA4DMMRSGQ> . You are receiving this because you commented.Message ID: ***@***.***>

[cmuellner]

I really appreciate the attempts to get CI/CD up and running.

However, I think we should copy from the psABI repo, as the workflow there has shown to work quite well.
We might make little adjustments (where necessary) or use more recent versions of external jobs, but overall, we should just do what can be found there: https://github.com/riscv-non-isa/riscv-elf-psabi-doc/blob/master/.github/workflows/build.yml

@axel-h, if you are interested then feel free to adjust this repo's workflow accordingly. We may also look at https://github.com/riscv-non-isa/riscv-elf-psabi-doc/blob/master/.github/workflows/remove-old-artifacts.yml.

For the particular issue that is discussed here, the psABI workflow file does what is expected by the "Upload release asset" step of the "draft-release" step. See https://github.com/riscv-non-isa/riscv-elf-psabi-doc/blob/master/.github/workflows/build.yml#L59.

[wmat]

In this particular instance the build fails due to an error in the PDF theme. I've fixed the error in docs-resources and am trying to update the submodule now, which is being stubborn for some reason. If necessary, I'll just delete it and start from scratch.

[axel-h]

The build worked, we have an artifacts zip in the action with a nice PDF. Just the draft release is not visible. I will have a look into this, as this also looks a bit odd in my fork. Seems the action needs some fine tuning. I had a look at the other project actions when creating this, seems a subtle detail that I got wrong there.

@wmat please push the template fix then also if this is another improvement.

[cmuellner]

@axel-h, I've created a PR to add the CI/CD scripts from the docs-template repo (https://github.com/riscv/docs-spec-template/tree/main/.github). See #118.

To avoid fragmentation, I also filed similar PRs to harmonize the CI/CD scripts of the C-API and the Toolchain Conventions as well. See riscv-non-isa/riscv-toolchain-conventions#66 and riscv-non-isa/riscv-c-api-doc#98.

[wmat]

Just wondering if someone could go ahead and create this release soon? I get asked almost weekly where the latest release is. I'm happy to help do this if everyone is busy. Just ping me.

[apazos]

Hi @wmat what do you plan to improve from the draft already available at https://github.com/riscv-non-isa/riscv-asm-manual/releases?

[wmat]

Hi @wmat what do you plan to improve from the draft already available at https://github.com/riscv-non-isa/riscv-asm-manual/releases?

All I was looking for is the addition of the "create a release" step within the GH action in the same way it occurs in other repositories. That way the top of tree release will always have a link from the repo's landing page on the right hand side. The reason for this is that there is a broken link in the Unprivileged ISA manual (in Chapter 2) to the ASM manual and the person who pointed it out is asking for a link to fix it with.

[apazos]

Thanks @wmat for clarifying what you want to fix, please go ahead with the change.
Please add the missing GH action.
I will then try to propagate your change to our other doc repos to keep them in sync with GH workflows.

[wmat]

It looks like nothing is missing, however the 'Create Release' portion of the GH action requires that it be manually dispatched. Can I simply do that and create a release?

[apazos]

Yes, I think it is fine to proceed with this action, as it will generate a link to it on the repo's page, which can then be referenced in other documents.

Please explain the process you do so I can replicate it in our other repos we own.