Do you have some thoughts, ideas about the API for...

# github-workflows-kt

[Ben Keil]

Do you have some thoughts, ideas about the API for workflow permissions?

current implemented solution:

some repetition

workflow(
    name = "test",
    permissions = listOf(
        Permission.actions.read,
        Permission.checks.read,
        Permission.contents.write,
    )
    on = listOf(),
) {
    job(id = "job", runsOn = UbuntuLatest) { run(command = "ls") }
}

other ideas:

everybody understands a map, a lot of repetition

permissions = mapOf(
    Permission.Actions to Mode.WRITE,
    Permission.Checks to Mode.WRITE,
    Permission.Contents to Mode.WRITE,
),

no repetition, maybe unusual

permissions = {
    actions(write)
    checks(write)
    checks(none)
    actions(read)
},

current style of API, but no autocompletion in IDE.

permissions = listOf(
    Actions(write),
    Checks(read),
    Contents(none),
),

[Piotr Krzemiński]

I would lean towards the second one because it's simple - it uses a well-known mapOf (also mirrors how YAML looks), provides proper discoverability for available permission and mode values. If one wants, it's possible to reduce repetition by importing individual enum values

[Piotr Krzemiński]

@Ben Keil what would you recommend or be eager to use as lib user?

[Ben Keil]

I think the map is the easiest thing, because it corresponds the most with the yaml specification

[Piotr Krzemiński]

@Vampire any opinion worth sharing here?

[Piotr Krzemiński]

it’s a small piece of API but as Ben is ramping up, he’s (correctly) challenging certain design decisions for already existing APIs. We had some interesting discussions about it

[Vampire]

Actually, the only repetition I see in the original code is Permission. which could be mitigated by imports.

Whether it looks like Yaml or not I don't think is too important. Yes, it might make it easier to onboard new users coming from Yaml. But, you know, noone likes Yaml, so don't create something that looks like Yaml or noone will like it. 😄

But besides that, if I have to choose from the 4 options, I'd probably also pick the map one.

[Piotr Krzemiński]

yeah, good argument with “don’t create something that looks like YAML” - I wasn’t thinking this way until we had the discussion with Ben

[Vampire]

It's no problem if it looks like Yaml. Just don't pick any choice in any decision because it looks like Yaml. Pick it because it makes the most sense independent from output format. And if it looks similar, win-win. 🙂

[Ben Keil]

so it will be the map