Setup workflow

[iaindillingham]

If users copy-and-paste .github/workflows/setup.yaml from this repo to their study, then their study may fail with a hard-to-understand error. For example, here the setup workflow is trying to commit changes to main, but main is a protected branch.

The setup workflow is valuable when this repo is used as a template; it's less valuable when it's used as a place from which useful code can be copied-and-pasted into another study. Could we:

• Warn users about copying-and-pasting the setup workflow?
• Improve the setup workflow?
• Something else?

Thanks for raising this issue, @milanwiedemann.

[lucyb]

We should warn users not to copy and paste the setup workflow. Point to the documentation, so they use it as a template instead.

[bloodearnest]

Where should this warning go? Putting it the README feels wrong, as thats supposed to be the public face of the repo.

[ghickman]

While documentation is definitely good, there's the possibility of documenting things before they're a problem. We don't want to dilute our docs with edge cases which rarely, if ever, happen.

A useful thing to ask ourselves here is "has an external researcher been caught out by this?" and base our decision on that. Internal researchers, and congrats to @milanwiedemann for being what I think might be first on this particular error 😁, know more about how our system works. That knowledge can lead to using tools in unexpected ways.

In this particular case I think it's most important to find out if this has come up before, and if not park/close/block this ticket until it's come up another couple of times to confirm it's not just a happy accident this time.

[sebbacon]

Definitely agree George.

I wondered if a short comment in the yaml is sufficient, without being over-the-top, though; thoughts?

[ghickman]

Yeah, a one-liner at the top, something like "this should only be included in repos generated from a template on GitHub".

[iaindillingham]

Would it be possible to have a more informative error message? So if you do copy-and-paste the study, and it does error, then the Actions tab is more informative.

[ghickman]

Maybe, but my argument here is essentially "is it worth it?". Does the screw driver packaging warn against using the handle as a hammer? (ok not a great argument because that obviously works 😂)

My feeling is, at this point where it's only happened once, probably not. If it happens another couple of times then it's probably worth the time cost.

[sebbacon]

We have obviously wasted far too much time on this already.... but just for the sheer joy of keeping the conversation going, the alternate view is that it cost someone a lot of time working out what happened, and the comment would prevent that happening again, however unlikely it is.

I strongly agree with your argument it it related to user documentation, but I'm less convinced if we're just talking about a comment. We actively litter our code liberally with probably-never-again-relevant comments.

Anyway wontfix this already, I don't really care :laughing:

[ghickman]

just for the sheer joy of keeping the conversation going

Just one more thing 😜

[sebbacon]

and another one

[iaindillingham]

[milanwiedemann]

thanks everyone, seems like we're coming to the end of season 1 😞 I enjoyed following and will of course try my best to find more errors like this

[bloodearnest]

Closing as won't fix as per the exciting discussion above.