Add as a starter workflow for Haskell

[chungyc]

It would be good if scanning with HLint was included as a possible starter workflow when adding a code scanning tool. This would increase the visibility of the option to scan Haskell code. It would also make it easier to add the workflow by providing a template workflow instead of the user having to copy-and-paste or typing in the workflow themselves.

I have a draft pull request to do this, but this is a change to GitHub-owned code, which means needing to sign a GitHub CLA and contributing code to GitHub. At least one of these tasks requires approval from senior management at my employer, and both involve cumbersome bureaucracy of one form or another. It doesn't have to be me that contributes a starter workflow to GitHub, but if it is to be me, it's going to take some time until these hurdles are cleared.

[chungyc]

If anyone on @haskell-actions/team is interested in driving this issue, especially if they have a CLA already in place with GitHub, I would be happy to hand over the reins.

[andreasabel]

which means needing to sign a GitHub CLA and contributing code to GitHub.

I got stuck at this point as well. Not sure if I can sign this as a private person, it does look like they want a company or similar, and I cannot act on behalf of Chalmers University...

[andreasabel]

which means needing to sign a GitHub CLA and contributing code to GitHub.

If anyone on @haskell-actions/team is interested in driving this issue,

Maybe we can get some help from the Haskell foundation here, @Kleidukos?

[david-christiansen]

HF here :-) I'd like to help, if we can.

My understanding based on a call with @Kleidukos is that a CLA is needed because GitHub wants to own the copyright to everything in their site, for understandable reasons. Presumably, they want to involve employers because many (most?) jurisdictions by default consider essentially all code produced by an employed programmer to be works for hire by their employers, which implies that the employer is likely to need to sign off on/perform copyright transfers.

I think that the HF can only sign a CLA for code that the HF is the copyright holder on. I think this implies having someone who works for HF produce the code that's needed here, and then going through the process of contributing. Getting @chungyc's employer to transfer ownership to HF is almost certainly not substantially easier than getting them to do the same for GitHub directly.

Is this a correct understanding? Have I missed something?

[chungyc]

Yes, that is basically correct.

There are a number of avenues I can pursue to contribute a starter workflow myself, but they will take much more time and/or effort (at least I don't think my employer will say no). It will certainly be far more than cobbling up a starter workflow, which is simple and should take less than 30 minutes for someone who knows what they're doing (and I can help with the knowing; not much is needed).

[david-christiansen]

All right, I'll see what I can work out. Thanks for the confirmation!

[chreekat]

Hey @chungyc, depending on what is needed I might be available to do this work on behalf of the Haskell Foundation.

Is it correct that the only thing I'd need to "reimplement" (in order to own the copyright, so I can legally give it to GitHub) is your draft PR against action/starter-workflows?

If that's the case, to avoid any copyright risk it's best if I write a "clean" implementation, just so we are completely covering our butts and guaranteeing we don't get your employer in trouble. :) That means I haven't looked at your PR. Can you just give me a bullet point spec of what it does? I'm not totally up to speed on GitHub Actions yet.

[chungyc]

@chreekat, I've written down everything I think is relevant. When you open a pull request against starter-workflows, it will include a checklist of what should be done as well.

Files

Two files need to be added in the code-scanning directory, according to the documented directory structure. They must have the same base name, let's say haskell-hlint, in different directories, e.g., code-scanning/haskell-hlint.yml and code-scanning/properties/haskell-hlint.properties.json. The former defines the workflow, and the latter metadata properties for the workflow. If you open a pull request, it will have a checklist item saying the the files should have the language or platform as its name.

Workflow

It should trigger on pushes to the default branch and protected branches, and on pull requests to the default branch. It also suggests running it weekly. This will be explained in the checklist that will be included in a pull request. codeql.yml or scorecard.yml may be good examples to see what's supposed to be done. You can ignore strategy fields, so the latter may be a better example for our purposes.

The actual steps in the workflow should be simple, and only two steps are necessary. They just need to be a actions/checkout action for checking out the repository and a haskell-actions/hlint-scan action for doing the actual scanning and upload of analysis results. We don't need to pass any special parameters with a with field.

Uploading the analysis results requires write permission for security-events. Reading the repository needs read permission for contents. I think running an action in a private repository needs read permission for actions.

The workflow file needs a blurb disclaiming that it's not by GitHub. The pull request should include exactly what needs to be included in one of its checklist items.

If you need a reference to GitHub action workflow syntax, it's on GitHub Docs.

Properties

See https://github.com/actions/starter-workflows#valid-properties for what needs to go into a *.properties.json file.

You could paraphrase the name and description from the action's GitHub Marketplace entry: https://github.com/marketplace/actions/scan-code-with-hlint

It would be nice to have a Haskell logo for the icon, and fortunately, they already have it at icons/haskell.svg, so we don't need to add a separate image. We can just use the existing image for the icon.

For categories, they have a list of general categories and a language category you're supposed to specify. The list of "Code Quality", "Code Scanning", and "Haskell" seems like a good choice.

Pinning actions

According to starter-workflows/CONTRIBUTING.md, actions not in the github.com/actions organization need to be pinned to a specific SHA, a.k.a., the commit ID. In other words, actions in the workflow must be in the form

uses: haskell-actions/hlint-scan@a99e50c562954d0c73211df1d7dabd33128b1098

for the v1.0.0 release, and not

uses: haskell-actions/hlint-scan@v1

I hope this is enough. Let me know if you need any other help! And thanks!

[chreekat]

Wow @chungyc, that is phenomenal!

We're still waiting to get into the partner program, but once that's done, I'll certainly be able to write the PR with such a detailed explanation. Thanks!

[chreekat]

FYI I'm still just waiting to hear anything about the GitHub Partner Program.

[chreekat]

@david-christiansen how about you, have you heard anything about the partner program?

[david-christiansen]

I have not.

[github-actions]

No activity with issue for 90 days.

[chreekat]

Hmm.. I can try to follow up on this.

[chungyc]

I'm going to try getting approval from my employer to contribute the starter flow. I had thought it might be much quicker for another organization to get a contributor license agreement, but apparently it's a lot harder than I expected.

[andreasabel]

@chungyc If you get anywhere, please let me know! We also want this for the setup action:

• Update github actions starter workflow for Haskell setup#59

[github-actions]

No activity with issue for 90 days.

[andreasabel]

@chreekat Any progress?

[chreekat]

@andreasabel negative.

[github-actions]

No activity with issue for 90 days.

[github-actions]

No activity with issue for 90 days.

[chungyc]

FYI, I have finally gotten around to doing the first steps to getting this done, namely, writing up a one-pager for approval from those who have no idea what this is. I will update with any progress.