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
• Less internal assumptions and more configuration parameters and sub-commands

Runtime

• PROD as a run mode is confusing when the environment also has something called "production". Change the run modes to DEV and STANDARD #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

• Data graph test infrastructure epic #626
• Add PR deploy previews to assist design review #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

• Reduce docker image sizes and build times
  • "finalize" script in the base docker image that other images can call to automatically slim down their image
  • Use esbuild to make services tiny
• Monorepo: Make '@typescript-eslint/no-use-before-define': 'error', compliant #350
• Adjust JSDoc linting to better suit our needs.
• 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?
• 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
• Dependabot schedules don't work all that well. Maybe investigate renovatebot as an alternative.
• 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.
• Add a GH Action/comment/check to show what the versions will end up as when the PR is merged in. #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"
  }
}