Document what this action actually does

[fingolfin]

We should document what this action does, in particular:

1. which information it takes from PackageInfo.g and how it uses that
2. (this includes the hint how we decide which archives types to create!)
3. that we invoke autogen.sh (something we might reconsider in v4 ?)
4. which files we copy or don't copy
5. where the tarballs are uploaded (to a GitHub release!)
6. that this action does not update a website, deliberately, but that one can use the update-gh-pages action to do that (and that it is separate to enable power users to host their package website elsewhere)

On point 4, I just noticed we do this:

    - name: "Make copy of package"
      shell: bash
      run: |
        mkdir -p "$RUNNER_TEMP/$BASENAME"
        cp -r * "$RUNNER_TEMP/$BASENAME"

Doesn't this mean we only copy files matched by * in the current dir, and hence won't copy files like .gitignore or the .github subdir? I guess that could be a feature, but (a) one we should document and (b) then we also don't need to worry about deleting those dotfiles in the very next step :-)

Perhaps I am missing something?

[stertooy]

By documenting, do you mean in the README, in comments in action.yml, or somewhere else entirely?

Anyway, I'll try to answer/comment on these here for future reference. Can move this to the correct place later.

1. From PackageInfo.g we collect:

   • The name that should be given to the release archives (from ArchiveUrl).
   • The git tag that should be used to create the release (from ArchiveUrl).
   • The name of the package (from PackageName). Used in the title of the release.
   • The version of the package (from Version). Used in the title of the release, and to prevent making a "dev" release.
   • The archive formats that need to be created (from ArchiveFormats)
   • Which PDF files should be attached to the release (from PackageDoc[].PDFFile).
   • The date the package should be released (from Date). Used to prevent making a release on the wrong date, which usually indicates the author forgot to update this in PackageInfo.g.

2. I'm not sure what you mean by this.

3. I don't know enough about this to have an opinion on whether or not we should invoke it. Could always let this be controlled by an input.

4. The actual release consists of:

   • An archive of the release, for every archive format that was specified in PackageInfo.g
   • A pdf file of every manual that was specified in PackageInfo.g
   • A package-info.json file, containing the info of PackageInfo.g in json form (used by e.g. the update-gh-pages action)

   The release tarballs themselves contain everything in the repository, except:

   • They contain any changes you made in your workflow after using checkout and before this action. Note that in particular you will likely have to call the build-pkg-docs action before this action.
   • Files related to git, GitHub, and any CI integrations are (hopefully) removed.
   • They contain any changes made by calling autogen.sh, if present.

5. The release tarballs, pdf files and package-info.json are uploaded to a GitHub release created (or overwritten) by this action. If you however initiated a dry run of this action, they are instead uploaded as workflow artifacts, to be found under the Actions tab of your GitHub repository.

Regarding point 4: The cp command does prevent most of these from being copied, although not requirements.txt (no idea what this is supposed to be). It also doesn't prevent dotfiles from being copied recursively, I think, whereas the first rm command
(rm -rvf .git* .hg* .cvs* .circleci) and the find command (find . -name .DS_Store -exec rm -f {} +) do.

[wilfwilson]

I think in 2., Max is referring to your point from 1.:

The archive formats that need to be created (from ArchiveFormats)

[fingolfin]

Sorry for being unclear, I meant documenting this in README.md: This action is supposed to be used by people who are not very technical, so asking them to "just look at the code in action.yml and figure it out" is not great. While "just look at the code comments in action.yml and figutre it out" is somewhat better, I think having this in README.md is best.

I stole some of @stertooy's text for PR #41

(The file requirements.txt exists in smallantimagmas and I think is from the Python ecosystem? Perhaps it was inherited from code by @limakzi ? Personally I think we should remove it from the action and leave it to packages to delete it in a custom step of their release.yml ... but this is a very minor point)

[limakzi]

@fingolfin Yes, it is from Python ecosystem; and yes - it looks like it was inherited.
I do use requirements.txt for automated gaplint updates with @dependabot.
It is completely unrelated with the code responsible for releasing a package.