-
Notifications
You must be signed in to change notification settings - Fork 34
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Ensure all options can be specified via CLI #31
Comments
(Follow-up on #29 (comment) and #29 (comment)): Below is a breakdown of current config options. Please let me know if you see any errors or ommissions.
type Release = "minor" | "major" | "patch";
type Task = "changelog" | "commit" | "tag";
type Hook =
| "prerelease"
| "prebump"
| "postbump"
| "prechangelog"
| "postchangelog"
| "precommit"
| "postcommit"
| "pretag"
| "posttag";
type TypePrefixes = Array<
(
| { section: string; hidden?: boolean | undefined }
| { hidden: true; section?: string | undefined }
) & { type: string }
>;
type ConfigFiles = Array<
| string
| { filename: string; type: "json" | "gradle" | "plain-text" }
| { filename: string; updater: string }
>; Some thoughtsUltimately, the difference between the CLI and JSON options are actually rather minimal. Only 1 option is wholly unavailable via CLI (unless I'm just not getting the syntax right), and 2 more are limited in functionality. How much work are those 3 options worth? Currently, some config options are dynamically generated by reading in the JSON schema for the The alternative would be to manually maintain the CLI implementation separate from the parsed JSON config and keep it up-to-date as the spec changes. The up-front work is higher, but I don't expect the spec changes frequently enough to present a huge maintenance burden. The upside is that we can get more creative: # lone strings are assumed to be filenames, and filenames delimit array items
$ commit-and-tag-version --packageFiles package.json manifest-beta.json type=json MY_VERSIONS.json updater=my-updater.js name=gradle.properties type=gradle
# or
$ commit-and-tag-version --packagFiles 1=package.json 2=manifest-beta.json 2.type=json 3=MY_VERSIONS.json 3.updater=my-updater.js 4.name=gradle.properties 4.type=gradle
# or, since `type and `updater` are mutually exclusive, we can use a single key and infer it as an updater if it isn't `json`, `gradle`, or `plain-text`
$ commit-and-tag-version --packageFile package.json --packageFile manifest-beta.json json --packageFile MY_VERSIONS.json my-updater.js --packageFile gradle.properties gradle PS: Last minute idea... what if everything is the same, but for those 3 args we add new CLI flags |
This is awesome!! Thank you so much! I'll have a proper read and detailed review tomorrow (in around 12 hours). My gut feel is that I like both the manual separate CLI suggestion (I think that separating the CLI parsing logic out from the options format will be a win), and the last minute idea (it seems simple). What's really missing at the moment is the ability to easily combine the two sources of options - I think the I think the key wins here will be:
Aside: I started looking at Commander for another project - looks awesome, thanks for the recommendation! |
Great catch! If possible, let's fix this. Maybe we can support both but leave one undocumented, so that it's not a breaking change? Also, I'm very aware this is becoming a sizeable piece of yak shaving 😂 . Please let me know if you'd like to reduce implementation workload by working on a branch together. Of course, if you'd prefer to just raise a PR when you're ready, that's fine too - I don't mind either way. |
In #61, it was reported that (currently) supplying invalid options doesn't cause the command to fail. Looks like moving to commander will fix that for free, though 🎉 |
Any thoughts on the order of precedence? Here's where I'm at:
I don't know if there's a certain ordering that is more or less intuitive to folks, especially when it comes to the order of precedence between There's also the option of making certain config sources mutually exclusive - e.g., throw if there is more than one of |
For the config files I would say precedence is irrelevant, but the order they are looked for is. I would look for I think the same logic could be applied to That's how I have seen other utilities work anyway. |
@SharpSeeEr Is this a convention? If so, I'm all for sticking to the convention. I feel like I agree with you on the former point, but not on the latter. That's more of a gut feel though, so I'd love to see more feedback. Edit: It also occurs to me that, with #29 on the roadmap, we should enable (and recommend) |
I wouldn't be able to say if it is a standard convention or not. I have seen it done like that on at least one project. 😸 I'll concede the second point no problem. As for |
When they run it, yes... but all TS is JS at runtime. The benefit is the in-editor documentation via IntelliSense. Targeting |
I don't think there's much convention. For example, eslint's precedence order is:
Prettier's order is the reverse:
Both tools appear to pick one and then stop, which I didn't realise until finding those links just now. I don't think the order matters too much, as long as it's documented and not especially surprising (and not overly complicated from an implementation perspective). |
Right, then - we pick something and document it. Unless someone has a good reason for bikeshedding it, guess we can go with @SharpSeeEr's suggestion. That gives us:
(1), (2), and (3) are merged, with duplicate entries in (1) overwriting (2), etc. Is that about right? What do y'all think about the choice of not throwing in any of these cases - are we providing a foot gun? Edit: Updated to reflect recent discussions |
I can only think of good reasons not to bikeshed it 😎
I agree.
I wondered about this too. We do have the advantage that we have clear logging pathway in the console output. I don't have a strong view on what we should do, but here are my gut feels: I don't think we need to warn, as #28 is about a case where the user expected to be able to have the same options on the CLI as were specified in the package.json config (and at first glance their setup looked right to me - as would a case where you added one more bumpfile in the CLI arg). In the case of "this config file is completely ignored because that config file is more important", I think it would be nice to throw - as that would reduce surprise, reduce the possibility of failure, and encourage people to tidy up their repos. I think this ability is a nice to have, and not necessary if it increases complexity too much or is otherwise not wanted. If someone has a strong opinion that it should behave differently, I'm happy to agree - assuming it is documented and isn't a surprising behaviour. |
Sounds all good to me - I've updated that post to reflect the changes. One thing I would add is, for the last line item in #3, I think we should at least warn when there are conflicting options and an override occurs. I agree about CLI overriding config-file overriding package.json, though. That seems like what I'd expect. I've done some initial work on the switch to |
I can see providing a warning when two configs contain the same setting, but not when the override comes from the CLI. That may be what you all meant, but just wanted to be sure. |
Here's the start of this: #68 |
Couple of observations from converting to Typescript:
// --package-files package.json package2.json
{
packageFiles: ['package.json', 'package2.json'],
'package-files': ['package.json', 'package2.json'],
}
The three complex options (packageFiles, bumpFiles, types) definitely provide a challenge when it comes to the CLI. These three options are excellent concepts that I think will help us get to the best solution. (@helmturner - please take this as intended, that they truly are great ideas!) I think the concept of adding additional CLI options is the best way to go. --package-file package.json --package-file VERSION.md --updater ./md-updater.js Where the |
Some options can only be specified in the config files. Both #28 and conventional-changelog#912 would be solved if the
type
of the updater could be specifed via CLI.Since the options for
commit-and-tag-version
are not complicated, it would totally be possible to extend the CLI options to make sure that everything that can be specified by a config file can also be specified via CLI.Ideally this would be done without embedding json in the CLI options.
The text was updated successfully, but these errors were encountered: