Technical debt laundry list

[jharvey10]

This issue is to track anything and everything across the carbon-platform repo that we think could use improvement. It's meant to be long-living and might grow or shrink over time. Feel free to add additional categories as needed.

We can convert a bullet into an issue if we decide to pull it into a sprint.

Packages

API

• [ ] The auth APIs work, but they won't scale well to multiple providers in their current state. We could definitely improve this
• [ ] There are a few disparate function calls available to build up authentication and authorization of a request. This could potentially be improved through function chaining and some naming tweaks.
  • How cool would it be to have an API that was even more functional like:

    export getServerSideProps =
      auth(context)
        .requireValidUser()
        .requireTrue(isValidIbmUser)
        .requireSomeOtherThing(/*...*/)
        .then(() => {
          // actual function
        })
    

MDX Components

• [ ] Storybook demos are just a random iframe url which anyone could put as anything. We should have to register a storybook hosting URL at the library level

Micromanage

• [ ] Unit tests for micromanage-cli
• [x] Less internal assumptions and more configuration parameters and sub-commands

Runtime

• [x] #412
• [ ] It'd be nice to have something in-your-face when starting a service to know if you're running it in DEV mode or not.
• [ ] It'd be nice to log the service version when it first runs for debug purposes.

Logging

• [ ] Enhance API to allow execution time to be provided as an optional field

Misc.

• [ ] All of our public packages should have a docs overhaul and move their docs to their README.md file as opposed to deferring to the platform /docs/ folder.

Services

Web App

• [x] #626
• [ ] #519
• [ ] Accessibility Testing (Accessibility Checker) on all web-app pages
• [ ] Create a safe() function to catch top-level exceptions for nextjs server side rendering and manifest the errors in a consistent way

Tooling

• [x] Reduce docker image sizes and build times
  • [x] "finalize" script in the base docker image that other images can call to automatically slim down their image
  • [x] Use esbuild to make services tiny
• [x] #350
• [ ] Adjust JSDoc linting to better suit our needs.
• [x] Deploying to test is more "manual" than it should be. What about automatic PR creation that updates the services to the latest every few days?
  • This will be done implicitly once we move to k8s
• [ ] Our CI builds do bare-metal builds, but they don't do docker builds, which are what we actually deploy. Should we investigate doing both for better indications of failure?
• [x] There's a mismatch on the deployed-services/production branch. The service json file is called "prod", but it should be called "production" like everything else. This will involve a change to micromanage.
  • This will no longer be an issue once we move to k8s
• [x] Dependabot schedules don't work all that well. Maybe investigate renovatebot as an alternative.
• [x] Base images are built for every service during the nightly, but they're identical for all services. It should instead be built once and passed to the service build job steps.
• [x] #1045
• [ ] Linter rule for double imports like page-header/page-header (prefer index import) or imports from dist directories
• [ ] Can python3, make, and g++ be removed after sharp is installed during image builds?

Docs

• [ ] There should really be some docker documentation to explain how things are laid out and built, comparing it to how we do things locally when developing.

Schema

• [ ] Contribute our schema to the JSON Schema Store (https://github.com/SchemaStore/schemastore) so VS Code can validate our carbon.yml files without requiring installing the YAML Language Support by Red Hat (https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml) extension
  • [ ] Remove use and documentation of yaml-language-server comments in carbon.yml files
• [ ] Document other ways to validate with the schema by using VS Code user, workspace, or folder settings such as:

{
  "yaml.schemas": {
    "https://unpkg.com/@carbon-platform/schemas@v1/carbon-resources.schema.json": "carbon.yml"
  }
}