DISCUSSION: docs and docs process

[frankiebee]

This needs to be defined but to kick off the conversation heres what i think we should do in the near future i'm open to negotiations so feel free to comment. on any step we can open appropriate issues from here:

kinds of docs

• Inline ([in code] auto generated method docs)

  • Types
  • method docs
    • top level class
    • sub level class public methods

  ideally we have some kind of bot to make sure devs are updating inline docs i guess thats @johnnymatthews for now 💛

• High level usage docs (hand written)
  these kinds of docs can clutter code so they need a dedicated home lets figure that out my proposal is we have sdk/docs/examples that when updated get copied over to the docs repo so we arent responsible for hosting. @johnnymatthews will do this by hand for now and we'll figure out whats best when ready
  p.s.: @jawn we need to figure out how thats on the website? i guess that may also already be figured out and maybe @johnnymatthews already know about it?

• Run time docs

  • Error messages:
    • template error message class that has the wiki docs site or whatever, we should point to core if it's an error coming from core?
    • error codes for when messages change
    • try catch all promise and throw help full errors please 😅

• Contributing docs

  • internal docs: how to publish etc will live in dev/README.md
    • change logs should be hand written as apart of the version pr
    • change log titles should have what version of core they are compatible with
    • every version in major version 0 is not backwards compatible lol
  • how to build locally and contribute will live in the root README.md

• Commits / branches / tags

  • because we squash and merge the title of the pr or whatever should be the most descriptve commit idc about wips in branches
  • branches should look like: name/issue-number#tittle
  • release branches: release/v-name
  • release tag v-name|| v? @jawndiego read https://semver.org/ we will follow this when are major version is 1
  • type of releases:
    • "stable" includes @johnnymatthews
    • hot-fix does not need @johnnymatthews unless include docs but really should just link an issue
    • prerelease is the version branch

---

side note

Publish process: (for dev readme)

• craft version pr
  • version bump
  • change logs should be hand written as apart of the version pr
• minimum day ideally two day before ping @johnnymatthews on version bump pr set 48 hour timer
• after timer merge into main
• make sure we have a version tag
• check out version tag
• yarn burn
• yarn bundle
• yarn test
• create a tag push to main? this might be handled by yarn needs to be checked
• npm publish

[mixmix]

try catch all promise and throw help full errors please 😅

or catch, add context and throw again!

promise
  .catch(err => throw Error(err, { cause: "you forgot the endpoint!" })

[mixmix]

cc @johnnymatthews

[mixmix]

Could this end up in a Wiki?
It's kinda a checklist + a guide + process