docs: add design docs

[akashsinghal]

Description

What this PR does / why we need it:

adds design doc markdowns from personal hackmd to centralize repo
adds a table of contents

Which issue(s) this PR fixes (optional, using fixes #<issue number>(, fixes #<issue_number>, ...) format, will close the issue(s) when the PR gets merged):

Fixes #

Type of change

Please delete options that are not relevant.

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Helm Chart Change (any edit/addition/update that is necessary for changes merged to the main branch)
• This change requires a documentation update

How Has This Been Tested?

Please describe the tests that you ran to verify your changes. Please also list any relevant details for your test configuration

• Test A
• Test B

Checklist:

• Does the affected code have corresponding tests?
• Are the changes documented, not just with inline documentation, but also with conceptual documentation such as an overview of a new feature, or task-based documentation like a tutorial? Consider if this change should be announced on your project blog.
• Does this introduce breaking changes that would require an announcement or bumping the major version?
• Do all new files have appropriate license header?

Post Merge Requirements

• MAINTAINERS: manually trigger the "Publish Package" workflow after merging any PR that indicates Helm Chart Change

[akashsinghal]

@binbin-li @susanshi I downloaded my Hackmd docs and placed in this folder structure. Unfortunately, the comments are lost but moving forward we can retain via PR review. Please let me know if you think there's a better way.

Also, could you both commit your docs to this PR as well?

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Comparison is base (0943c02) 52.31% compared to head (ac83fd9) 52.31%.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1136   +/-   ##
=======================================
  Coverage   52.31%   52.31%           
=======================================
  Files         101      101           
  Lines        6306     6306           
=======================================
  Hits         3299     3299           
  Misses       2688     2688           
  Partials      319      319           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[binbin-li]

Just wonder if we should move design docs to this repo or ratify.dev?

[akashsinghal]

Just wonder if we should move design docs to this repo or ratify.dev?

I was modelling off of Gatekeeper. They check in the design docs into the main repository. And it doesn't get published to website. I think it makes sense since we don't want to consider it as official documentation. The design proposals don't necessarily reflect the exact implementation/behavior we have currently. It's more for historical preservation.

Having it in the main repo is helpful for keeping it all in one place. Also we might get more feedback on Design PR's if it's on the main repo.

[binbin-li]

thanks for adding it, lgtm!

[binbin-li]

@binbin-li @susanshi I downloaded my Hackmd docs and placed in this folder structure. Unfortunately, the comments are lost but moving forward we can retain via PR review. Please let me know if you think there's a better way.

Also, could you both commit your docs to this PR as well?

btw, do we need to open PR merging to your forked branch?

[akashsinghal]

@binbin-li @susanshi I downloaded my Hackmd docs and placed in this folder structure. Unfortunately, the comments are lost but moving forward we can retain via PR review. Please let me know if you think there's a better way.
Also, could you both commit your docs to this PR as well?

btw, do we need to open PR merging to your forked branch?

As maintainers, I think you can just the check the PR out locally and then push to that branch. Either way works. I can also merge this PR and you can send a follow up.

[akashsinghal]

@binbin-li @susanshi I will merge this PR first. If you could send follow up PRs with your design docs added, that would be great.