Migrate all commands to cobra style commands

[ahrtr]

We have already implemented part of the surgery command as cobra style commands, https://github.com/etcd-io/bbolt/blob/bd7d6e9f18bc139836feccb576339fbb8254fb41/cmd/bbolt/command_surgery_cobra.go#L28

We need to migrate all other commands to cobra style commands,

• bench
• buckets
• check
• compact
• dump
• get
• info
• keys
• page
• pages
• page-item
• stats
• surgery (@ahrtr will take care of the rest of surgery commands)

We can create a separate file for each command, such as command_page.go for the bbolt page command. Please anyone feel free to drop message if you are interested in migrating any command.

I will provide an example PR soon.

[serathius]

Idea seems right to me, however from what I see https://github.com/etcd-io/bbolt/pull/473/files makes a breaking change on command line from bolt surgery revert-meta-page SRC DST to revert-meta-page <bbolt-file> [options] where --output is an optional flag.

I think this is ok for new commands like surgery, however what's your plan for old commands. Do you plan breaking changes here? If not, how sure we are in our tests to prevent missing any edge cases?

[ahrtr]

Do you plan breaking changes here?

For bbolt golang public API, we will keep them compatible in all 1.x releases.

For commands, we have two options,

• 1. Migrate all new commands (e.g. surgery) to surgery style commands in master (1.4.0), and migrate all old commands in 2.0+;
• 2. Migrate all commands to cobra style commands, as It isn't good to have mix command styles. Yes, it's breaking change.
     • If users want to keep using old style commands, they just need to use 1.3.6 or 1.3.7 commands even they bump the bbolt to 1.4.0;
     • Given the long release cycle, it might be accepted.

If not, how sure we are in our tests to prevent missing any edge cases?

What edge cases?

[serathius]

cc @ptabor

What edge cases?

Just making a point that before refactoring the codebase we should double check out test coverage for command line surface.

[ahrtr]

Just making a point that before refactoring the codebase we should double check out test coverage for command line surface.

It's a good suggestion. Currently we have test cases for most of the commands. Only three commands (check, page and page-item) do not have test cases. We can add test cases separately. Note that the surgery commands (which are not migrated yet) are in a separated & dedicated file, they are almost isolated with other old commands.

[ahrtr]

Just added test cases to cover all the commands which do not have cases before. https://github.com/etcd-io/bbolt/pull/474

[ahrtr]

The plan is to migrate all surgery commands to cobra style commands firstly. Please take a look at the first PR https://github.com/etcd-io/bbolt/pull/473

Afterwards, we can discuss whether to migrate other old commands. Should we keep it compatible for all old commands?

[serathius]

Do you plan breaking changes here?

For bbolt golang public API, we will keep them compatible in all 1.x releases.

For commands, we have two options,

• 1. Migrate all new commands (e.g. surgery) to surgery style commands in master (1.4.0), and migrate all old commands in 2.0+;
• 2. Migrate all commands to cobra style commands, as It isn't good to have mix command styles. Yes, it's breaking change.
  • If users want to keep using old style commands, they just need to use 1.3.6 or 1.3.7 commands even they bump the bbolt to 1.4.0;
  • Given the long release cycle, it might be accepted.

Based on my experience in K8s community I think maintaining backward compatibility is very important. My preference would be to do a proper migration similar to what we did for etcdctl. By default keep the old behavior, and allow users to switch to cobra style arguments by passing environment variable. However this will be time consuming I leave it up to you to decide if you can invest the time.

[ahrtr]

The plan is to migrate all surgery commands to cobra style commands in 1.4, and migrate all other old commands in 2.0. Does it make sense?

By default keep the old behavior, and allow users to switch to cobra style arguments by passing environment variable

It's a good suggestion in general; but I really don't want to complicate the bbolt CLI, and don't want to spend too much time on it.

[charles-chenzz]

We can create a separate file for each command, such as command_page.go for the bbolt page command. Please anyone feel free to drop message if you are interested in migrating any command.

I will provide an example PR soon

can you link example PR or are there refs? would like to help migrating part of the command @ahrtr

[charles-chenzz]

/cc @jmhbnz

[jmhbnz]

Hey @charles-chenzz - Please refer to https://github.com/etcd-io/bbolt/pulls?q=is%3Apr+migrate+cobra+style for examples of pull requests migrating commands to cobra style.

[ahrtr]

can you link example PR or are there refs? would like to help migrating part of the command @ahrtr

Thanks for the help. As I mentioned in https://github.com/etcd-io/bbolt/issues/472#issuecomment-1536207021, migrating other commands to cobra style commands is a breaking change, so we decided to do it in 2.0.

[charles-chenzz]

Thanks for the help. As I mentioned in https://github.com/etcd-io/bbolt/issues/472#issuecomment-1536207021, migrating other commands to cobra style commands is a breaking change, so we decided to do it in 2.0.

we slowing migrate parts of them from 1.4 - 2.0 or we plan to start the other migrate in one shot in 2.0? I already have a PR wip. If we do in one shot then I need to hold the PR

[ishan16696]

Hi @charles-chenzz ,

I already have a PR wip. If we do in one shot then I need to hold the PR

are you working on all of bbolt commands ? I have created checkboxes to track progress and assignees for each bbolt commands.

• [ ] bench
• [ ] buckets
• [ ] check
• [ ] compact
• [ ] dump
• [ ] get
• [ ] info
• [ ] keys
• [ ] page
• [ ] pages
• [ ] page-item
• [ ] stats
• [x] version (done by @ishan16696)
• [x] surgery (done by @ahrtr)

[Elbehery]

@ahrtr shall i take this on ?

[charles-chenzz]

hi @ishan16696 , I was working on part of it. please feel free to take on.

[Elbehery]

@ahrtr i can take this 👍🏽

[tommyshem]

I can do the the info command next when the buckets command above is ok to merge

[Elbehery]

@ahrtr hello

I thought we are holding this on, due to breaking changes, or ?

[ahrtr]

@ahrtr hello

I thought we are holding this on, due to breaking changes, or ?

As long as there isn't any behavior change from users' perspective, then it's OK to get it done in 1.4.

[ivanvc]

Just confirming that we're not considering a behavior change that Go flags are not POSIX compliant (single dash) and that it's okay to replace them with pflags (double dash/POSIX compliant)?

If we're okay with this change, I think we can start splitting the work. I originally migrated bench, but now it's outdated because of performance improvements and the addition of random read capabilities. So, I'd like to be assigned to bench.

[ahrtr]

Just confirming that we're not considering a behavior change that Go flags are not POSIX compliant (single dash) and that it's okay to replace them with pflags (double dash/POSIX compliant)?

single dash to double dash should be a breaking change.

[tommyshem]

the buckets command has no flags only the path argument

[tommyshem]

PS C:\tmp\fork\bbolt1\cmd\bbolt> .\bbolt.exe page -h usage: bolt page PATH pageid [pageid...] or: bolt page --all PATH

Additional options include:

    --all
            prints all pages (only skips pages that were considered successful overflow pages)
    --format-value=auto|ascii-encoded|hex|bytes|redacted (default: auto)
            prints values (on the leaf page) using the given format.

Page prints one or more pages in human readable format.

the above is the output from the page command . It's from the original code and it already uses double dash flags e.g. --all flag

[Elbehery]

Just confirming that we're not considering a behavior change that Go flags are not POSIX compliant (single dash) and that it's okay to replace them with pflags (double dash/POSIX compliant)?

If we're okay with this change, I think we can start splitting the work. I originally migrated bench, but now it's outdated because of performance improvements and the addition of random read capabilities. So, I'd like to be assigned to bench.

+1, we can split the required work here, feel free to assign me on this 👍🏽

[ivanvc]

@Elbehery, I think a good starting point would be checking which commands don't have flags. These would be good candidates to be migrated without breaking changes.