Jump to content

Wikimedia Cloud Services team/EnhancementProposals/Decision record T348749 Toolforge CLI consolidation

From Wikitech

Origin task: phab:T348749

Date of the decision: 2024-01-30

People in the decision meeting (alphabetical order):

  • Andrew Bogott
  • David Caro
  • Raymond Ndibe
  • Francesco Negri
  • Slavina Stefanova
  • Taavi Väänänen

Decision taken

Option 4 was chosen.


Option 4 received the highest number of votes and was generally considered a good trade-off between leveraging the power of code autogeneration from an OpenAPI spec, and staying with Python as our primary client language.

Voting results

For each option, each participant voted using the "fist to five" method, where 0 means no support, and 5 means full support.

  • Option 1: 14
  • Option 2: 3
  • Option 3: 21
  • Option 4: 23


One of the outcomes of {T346153} is that we have decided to move forward with consolidating all the existing Toolforge CLIs into a single one. This is a follow-on decision request to decide on the details of how this should be done.

The CLIs are:

  • `jobs`
  • `webservice`
  • `build`
  • `envvars`
  • additionally, there's the `toolforge` wrapper

Risks & Constraints

  • We should avoid breaking the current user experience and overall CLI semantics
  • Regardless of the option chosen, care must be taken to not introduce or carry over technical debt that could complicate future development
  • Each option will require varying levels of development effort and time, which should be considered in the context of other ongoing projects and priorities

Option 1

Merge the existing Python CLIs

Option 2

Rewrite a CLI from scratch in Go

Option 3

Create a unified Open API definition for the CLI first, then autogenerate a Go client from it

Option 4

Create a unified Open API definition for the CLI first, then autogenerate a Python client from it

Note: This option was added during the decision meeting

The Pros & Cons for each option were added after discussion, but before voting.

Pros & Cons

1. Merge Existing Python CLIs

  • Uses existing Python code and expertise
  • Potentially quicker to implement due to familiarity
  • More accessible to new and less experienced contributors
  • Python's performance is generally slower compared to Go (cli speed is however not a bottleneck)
  • Lacks single-binary packaging which can be a limitation
  • Might require more effort for packaging and distribution

2. Rewrite CLI from Scratch in Go

  • Benefits from Go's performance and efficiency
  • Enables single binary packaging, simplifying distribution
  • Full control over design and implementation from the start
  • Inability to reuse existing Python codebase
  • Go's ecosystem is less rich compared to Python, which may limit certain functionalities
  • Potentially longer development time due to Go's relative verbosity and learning curve

3. Create a Unified Open API Definition, Autogenerate a Go Client

  • Lowers long-term maintenance due to autogeneration
  • Unified API could provide broader benefits and standardization
  • Reduces human error in coding
  • Ensures comprehensive API documentation
  • Time-intensive to create a complete and effective Open API specification
  • Autogenerated code may not fully leverage Go's features, possibly leading to less optimized solutions
  • Reliance on specific tooling and technologies for autogeneration
  • Like option 2, inability to reuse the existing Python codebase