docs: add semantic-release section

[drlkf]

I've managed to implement automatic semantic-release CI that uploads new
versions to Hackage automatically in my recently transferred
megaparsec-utils
package, I think it could be useful for other members to be able to do the same.

This new section documents how to make it work for your repository if you want
to use it as well.

EDIT: turns out I had forgotten to remove the HACKAGE_TOKEN secret, and since using the haskell_github_trust token, it does not have permissions to upload, even candidates. Is it conceivable to convert haskell_github_trust to an uploader on Hackage? Otherwise, people might have to configure their own personal token in the repositories, which is not ideal. Let me know what you think :)

[jamesdbrock]

Thanks @drlkf ! I have two things to say about this.

First, it is not possible to make the haskell_github_trust Hackage account an uploader account because this is against the Hackage policies.

Second, I would like to keep the main README terse and focused on explaining the basic organizational rules. I would prefer to have instructions about automatic release in a separate markdown file which is linked to from the main README file.

[drlkf]

it is not possible to make the haskell_github_trust Hackage account an uploader account because this is against the Hackage policies.

Ah I see, I'll contact the Hackage admin to see if they have a solution for organization accounts.

I would prefer to have instructions about automatic release in a separate markdown file which is linked to from the main README file.

Will do!

[drlkf]

After looking and asking around, I've got the following responses:

1. It seems to me organizational accounts are permitted, from the registration page:

Organizational, rather than individual, accounts are also permitted.

If you have another source that states it isn't, could you link it so I can ask which one prevails?

2. Here is the excerpt of my conversation on libera.chat#hackage:

    drlkf │ hi, i'm part of an organization that contains many maintainers and
          │ packages: https://github.com/haskell-github-trust ; i'd like to implement a
          │ hackage organization account to do semantic-release stuff, but another
          │ organization member informed me that it's against hackage policy to do
          │ that, is there a solution for organizations to have a shared hackage
          │ account or token to upload new versions of
    drlkf │ allowed packages without resorting to personal access tokens?
      f-a │ drlkf: Curious, how do you plan to handle malicious actors?
    drlkf │ f-a: do you have a specific threat model in mind?
geekosaur │ drlkf: the obvious one to me is an organization member leaves
          │ (or worse, is told to leave) but still has the shared account, so the
          │ password has to be changed and all other org members given the new password
geekosaur │ whereas if everyone in the org has their own account (which is
          │ how multi-maintainer projects such as cabal itself are handled) you can
          │ remove the account from the org maintainers list
geekosaur │ (which still leaves them able to upload their own packages
          │ unless someone specifically removes them from the uploaders group, which
          │ might be done by the trustees in extreme cases)
geekosaur │ consider https://www.akamai.com/blog/security-research/critical
          │ -linux-backdoor-xz-utils-discovered-what-to-know but instead done as
          │ retaliatory action
      f-a │ drlkf: A scorned developer inserts malicious code in one of the
          │ packages, or vandalised the github repo.
      f-a │ * vandalises
    drlkf │ geekosaur f-a: i suppose those are similar enough that i'd address them
          │ both at once, in that case having access to the uploader account removes
          │ about half a step from them doing the harm they intend, since they'd be
          │ able to do that regardless with their own account even if they didn't have
          │ the CI to upload; in which case contingency is to reset password and access
          │ tokens after removing them from
    drlkf │ the org and hackage packages, and contact hackage admins to remove
          │ malicious versions
    drlkf │ geekosaur: i'd like to avoid having people to put their personal account
          │ token in the repo CI, hence the shared account to handle normal releases on
          │ default branches, unless you're suggesting having CI uploads is a bad idea
          │ altogether?
geekosaur │ drlkf: in that case I think I'd make a dedicated Hackage
          │ account for CI uploads, with the relevant connection information as a GHA
          │ "secret"

The recommended method is quite similar to what I envisioned, except the secret contains the Hackage token and not username/password, which is readily available to use to all our members, so that threat model isn't mitigated. That being said, I would personally think this is an acceptable risk for making maintainers' life easier; we could also document that drawback somewhere else, but I doubt anyone would find it in an occurrence of such "incident".

If those security concerns are not acceptable, I'll just scrap the upload part of semantic-release. Let me know what you think :)