README
¶
oscar: the OpenSourceCorp Automation Runner
oscar ("OpenSourceCorp Automation Runner") is a highly-opinionated, out-of-the-box task runner.
Originally designed for use exclusively within OpenSourceCorp's CI/CD
subsystem, it is perfectly usable
outside of OSC as well.
oscar is "highly-opinionated" in that oscar is designed to do each thing one single way.
No choosing what linters to run or how to configure them, no picking which annual flavor of Python
or Nodejs packaging tool, etc. -- oscar is built to be the authoritative toolset for entire
teams and their codebases.
Under the hood, oscar uses the excellent mise quite heavily, and would
like to thank the author & contributors for making something like oscar possible without a lot of
wheel-reinvention.
How to use
Before getting started, note that oscar has a few host-system runtime dependencies. Some of these
may someday be replaced natively in the future, but some are integral to how oscar works
internally.
bash(version 4.4+)git
You run oscar by providing it a subcommand, such as ci. You can see the full available subcommand
list via oscar --help.
Features
| Feature | oscar command |
Details |
|---|---|---|
| Continuous integration | oscar ci |
section |
Continuous Integration
oscar ci runs a suite of continuous integration checks against your codebase, serving as something
of a linter aggregator. It provides these checks based on file discovery across your codebase, and
will only run checks based on what it finds. It also has behavior inspired by a tool named
pre-commit, including failing runs if any checks introduce Git diffs
during their runs.
Note again that these checks are highly opinionated -- if a particular linter supports
configuration, oscar configures it, but it uses its own built-in configuration. For example,
if you try to change the line-length limit rule for markdownlint-cli2 to be 120, oscar will
ignore your request and run the check with its built-in limit of 100. This behavior is
intentional, and serves to drive consistency across all manner of software that oscar could
possibly run against within a set of codebases.
However, this does not mean that someone is prevented from adding additional checks outside of
oscar's purview -- it just means that you cannot override what oscar does control.
Supported platforms
oscar is designed to run on Linux, and should work on macOS as well. Native Windows has not been
tested, and is unlikely to work. If you are on a Windows machine, you can run oscar in a WSL2
environment and it will work the same as on Linux.
Development & Contributions
Please see CONTRIBUTING.md for details about developing oscar.
Roadmap
- Add
VERSIONcheck comparing tomainas a CI task - Workstation setup
- Have
oscarmanage Makefiles, dotfiles, etc.
- Have
- CI additions
- Terraform
- protobuf
- Rust?
- CD additions
- Publish to ghcr
Documentation
¶
Overview ¶
Package oscar sits at the root of the repo, and allows us to embed files all the way down the tree.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var Files embed.FS
Files holds any embedded files for use elsewhere across the codebase. Notably, it also holds the 'mise.toml' file that is used for not only oscar's own development config but also for its internals.
Functions ¶
This section is empty.
Types ¶
This section is empty.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
oscar
command
Package main runs oscar.
|
Package main runs oscar. |
|
internal
|
|
|
ci
Package ci defines behavior for running CI checks.
|
Package ci defines behavior for running CI checks. |
|
ci/configfiles
Package ciconfig is used for storing embeddable config files for various CI tools, that are injected at runtime.
|
Package ciconfig is used for storing embeddable config files for various CI tools, that are injected at runtime. |
|
ci/go
Package goci contains logic for running CI tasks for Go.
|
Package goci contains logic for running CI tasks for Go. |
|
ci/markdown
Package markdownci contains logic for running CI tasks for Markdown.
|
Package markdownci contains logic for running CI tasks for Markdown. |
|
ci/python
Package pythonci contains logic for running CI tasks for Python.
|
Package pythonci contains logic for running CI tasks for Python. |
|
ci/shell
Package shellci contains logic for running CI tasks for Shell languages.
|
Package shellci contains logic for running CI tasks for Shell languages. |
|
ci/util
Package ciutil provides core types, helper functions, etc.
|
Package ciutil provides core types, helper functions, etc. |
|
cli
Package icli defines the command-line tooling for oscar.
|
Package icli defines the command-line tooling for oscar. |
|
consts
Package consts provides a shared place for constants & global variables for usage across the codebase.
|
Package consts provides a shared place for constants & global variables for usage across the codebase. |
|
git
Package igit defines logic for interacting with Git on the host.
|
Package igit defines logic for interacting with Git on the host. |
|
print
Package iprint contains helper functions for printing information for the caller.
|
Package iprint contains helper functions for printing information for the caller. |
|
semver
Package semver provides tooling for working with version information, in a way that conforms with the [Semantic Versioning] approach.
|
Package semver provides tooling for working with version information, in a way that conforms with the [Semantic Versioning] approach. |