Candidates for v1

[jcbhmr]

What should be in the v1 release? What's the criteria to get there?

Here's some ideas for options that I think make sense:

• strategy (or mode): subtree|force|clone -- default clone
• path: a path in the src tree -- default "wiki"
• repository: a github repo. optionally have a domain prefix like github.com/user/repo. -- default to ${{ github.repository }} -- should support dynamically determining if there's a host part to the url (2 slashes=host; 1 slash=default to github.com)
• commit-message (or commit_message): message to use in force and clone modes
• any other options from https://github.com/stefanzweifel/git-auto-commit-action
• token: github token to use for authentication with the wiki repository -- default ${{ github.token }}

Some other features that I'd love to see in a v1 or v2:

• helpful error message when the wiki doesn't exist
• helpful error message when token doesn't have right perms
• helpful error message when pushing to non-same repo's wiki
• helpful error message when path is outside repo
• a more in-depth comparison breakdown of the alternatives either in the readme or in a docs/comparison.md or similar

@spenserblack other stuff for a v1? how should progress to this goal be tracked?

[spenserblack]

• should support dynamically determining if there's a host part to the url (2 slashes=host; 1 slash=default to github.com)

I like this, great idea! 👍

• commit-message (or commit_message)

Let's stick with kebab-case. My opinions are purely aesthetic, but I'd like inputs to match the rest of the workflow syntax/style (like continue-on-error).

• token: github token to use for authentication with the wiki repository -- default ${{ github.token }}

I think a companion user input, to be able to change the foo in foo:${{ inputs.token }}, would be reasonable for now.

---

As far as helpful error messages go, there are 2 things we can do:

1. Try to make the initial v1 release as good and pretty as possible
2. Put out a minimally viable v1 release, add in error messages (which are practically guaranteed to be non-breaking) later

Personally, I don't like it when a release is delayed because the maintainers want to cram as many features in as possible. So my vote is get v1 out with the new usage (inputs), and then incrementally improve v1 with the helpful error messages.

I don't think the comparison needs to be versioned, and can just be treated as a living document that gets updated as needed. In other words, I don't think that updating this doc should delay a release.

---

As far as progress goes, I think that we may discover that a lot of inputs are dependent on what strategy/mode is selected, so I think it makes sense for that to be the first thing that is tackled for v1. Frankly, perhaps even adding in strategy/mode alone could be the v1 release, then other dependent inputs are added in to v1.x releases.

What do you think?

[jcbhmr]

I think a companion user input, to be able to change the foo in foo:${{ inputs.token }}, would be reasonable for now.

is this even needed? i think more investigation is needed before knowing if the user even needs to be there at all.

so far, for ${{ github.token }} PATs, we know it doesn't, but u mentioned testing it with user-generated CLASSIC and BETA-GRANULAR tokens too.

maybe looking at code/impl of the actions/checkout thing would be a good idea? heck, since this a composite action, we can just reuse it if nothing else like

steps:
  - uses: actions/checkout@v3
    repository: user/repo.wiki
    ...

Personally, I don't like it when a release is delayed because the maintainers want to cram as many features in as possible. So my vote is get v1 out with the new usage (inputs), and then incrementally improve v1 with the helpful error messages.

sounds good 👍

As far as progress goes, I think that we may discover that a lot of inputs are dependent on what strategy/mode is selected, so I think it makes sense for that to be the first thing that is tackled for v1. Frankly, perhaps even adding in strategy/mode alone could be the v1 release, then other dependent inputs are added in to v1.x releases.

my brain 🧠 has been convinced by your "I don't like it when a release is delayed because the maintainers want to cram as many features in as possible" sentiment to take an even more conservative idea: don't even put in a strategy/mode option at v1, save that for v2

[spenserblack]

don't even put in a strategy/mode option at v1, save that for v2

Really, it could be a v1.1 release, as long as the v1 behavior remains the default strategy 🙂