Provide documentation and cli tool framework for various internal .NET Core engineering repos / teams.
We have a handful of internal cli tools in various repos, and the number is increasing. We need to provide consistent guidance and tooling support for various cli requirements so that we can manage our cli's using our own engineering (Arcade) principles. This epic is specifically targeting internal cli tool usage. Public tools (such as darc), may follow some of the same conventions / guidelines, but are not specifically targeted as part of this effort.
Today, there is very little consistency between cli's in terms of testing, support, documentation, contribution guidelines, usage, etc... We need to provide a common cli framework to address cli needs while keeping the barrier for contribution / participation low and the tooling "lightweight". The framework will provide common conventions which allow the cli tools to meet the business objectives defined below.
The framework will be an MSBuild SDK and/or packages which permit CLIs to be built using the common tooling.
OSOB Cli has some functionality which is tightly coupled to source, and some which is not. Cli tools which are very tightly coupled to source will adopt some of the shared tooling (common command parsing, etc...), but won't necessarily adopt all tooling (doesn't publish). We can pull the functionality out of osob cli which is not tightly coupled to source and move it into another cli which does utilize the full tooling.
- .NET Engineering area representatives agree that the cost for participation in shared cli tooling should is reasonable and would not prohibit an area from using shared tooling.
- Osob representative
- Helix representative
- Secret management representative
- .NET Engineering area representatives agree that the release model is sufficient for their needs
- Release cycles for participating Cli tools are documented
- Cli tool framework uses a common, defined versioning scheme
- Participating Cli tools are debuggable
- Exact source code is determinable from any version of a tool
- Cli tool ownership is identifiable
- Contribution guidelines are documented
- Cli tool(s) purpose and functionality are documented.
- Cli tool(s) are discoverable
- Note: A couple of ideas: (1) an automatedly updated repo's readme file with links, (2) a utility cli tool that looks for packages in a specific feed and lists them as installable cli tools, or another model (sort of a hybrid pseudo plugin shell).
- .NET Core engineering team members with internal cli tooling needs
- First responder team
- Tool should be lightweight
- Contribution should be easy and well defined
- Testable
- Tools should share a common command structure
- Tools should be discoverable
- Shared infra (Arcade principles)
- Burdensome requirements for participation may lead devs to use one-off scripts for common needs rather than participating in shared tooling
- Release cycle requirements which are not thought through may lead to cli tools which can not be serviced or would affect servicing releases
- Cli tools should be serviceable without impacting product releases
- Usage will be tracked in application insights
- Grafana alerts and build results
- Contribution guidelines
- Versioning
- Release model
- Tool scope / intent
Ongoing support agreement for shared Cli tooling is defined
@chcosta Some random thoughts I have: