Common Package Schema

[dendron-bot]

Context

With Dendron, it is possible to effectively externalize knowledge so that individuals and organizations can rely on a shared mental model (aka schema) for referencing knowledge.

The following is the module schema which we use to organize code at Dendron. It is very much a work in progress and we welcome any and all suggestions.

Schema

• format using inline schema format as described in [[35 Easier Schemas|dendron://dendron.dendron-site/dendron.rfc.35-easier-schemas]]
• you can see an example of a hiearchy implementing this schema at [[pkg.plugin-core]]

- title: module
  namespace: true
  children:
    - title: quickstart
      desc: how to start development
    - title: dev 
      desc: regular development process
        - title: troubleshooting
          pattern: trouble
    - title: qa
      desc: quality assurance
      children:
        - title: debug
        - title: test
        - title: performance
          desc: how to profile code
    - title: ops
      desc: handle operational issues
      children:
        - title: logs
        - title: errors
        - title: deploy
    - title: architecture
      pattern: arch
      desc: general architecture for the module
      children:
        - title: lifecycle
        - title: state
          desc: how we manage state
    - title: concepts
    - title: topic
      pattern: t
      detail: A major component of the current module. Children are also modules
      namespace: true
    - title: reference
      pattern: ref
      detail: A minor component of the current module 
      namespace: true

Wildcards

Wildcards are nodes that can be put as the children of anything. They can also live as sections inside a note

Nodes

• Cook: Guide on how to accomplish a specific task
  • eg: [[Cook|dendron://dendron.dendron-site/pkg.plugin-core.dev.cook]]
• Tip: Optimizations on doing things better
  • eg: [[Tips|dendron://dendron.dendron-site/pkg.plugin-core.dev#tips]]
• Gotchas: Things to watch out for
  • eg: [[Gotchas|dendron://dendron.dendron-site/pkg.plugin-core.dev#gotchas]]

Types

Wildcard as Child of Note

• hiearchy: {module}.dev.cook
  • how to do X in a certain module

Wildcard as Section of Note

• {module}.dev

## Cook

### Adding a new command to plugin-core

...

Choosing betwen Child vs Section

Following the [[Amoeba pattern|dendron://dendron.dendron-site/dendron.workflows.amoeba]], wildcards should start of as sections of existing notes. If the content needs to be used in multiple places or exceeds 800 lines of text, it should be refactored into a child

Ref vs Topic

A topic is a major component that requires its own module hiearchy to properly document. For example, [[Lookup|dendron://dendron.dendron-site/pkg.plugin-core.t.lookup]] is a topic of plugin-core.

A reference is a minor component that should hang as a leaf and should be self contained. For example, [[Decorations|dendron://dendron.dendron-site/pkg.plugin-core.ref.decorations]] is a reference in plugin-core because it is specific to VSCode.

Examples of using the schema

How do I get started developing?

• schema: {module}.quickstart
• eg: [[Dendron Plugin Quickstart|dendron://dendron.dendron-site/pkg.plugin-core.quickstart]]

How do I write or read logs?

• schema: {module}.ops.logs

How do I handle errors?

• schema: {module}.ops.errors

How do I create a new {X} in {Y}?

• schema: {module}.dev.cook
• eg: [[Add a new Command|dendron://dendron.dendron-site/pkg.plugin-core.dev.cook#add-a-new-command]]

Architecture

What is lifecycle of a given command?

• schema: {module}.arch.lifecycle

Testing

How do I write a test?

• schema: `{module}.qa.test

How do I debug a test?

• schema: `{module}.qa.debug

[nickolay-kondratyev]

    - title: topic
      pattern: t
      detail: A major component of the current module. Children are also modules
      namespace: true

Given that its a major component of a current module should we have some preset schema for the major component as well?

Its mentioned later in the doc that "A topic is a major component that requires its own module hiearchy to properly document." I am just not seeing from the schema how we assign the the module hierarchy to the topic.

---

If the content needs to be used in multiple places or exceeds 800 lines of text

800 seems like quite a large number to set for refactoring a section of the notes

[kevinslin]

we can definitely lower that number. it was just set as a starting point. do you have a preferred number?

the child of a topic should be a module. we don't currently have a way of expressing that because the module schema is a namespace.

ideally, we could do something like this

...
- title: topic
  # this means that this schema extends all the same properties as the top level `module` node
  extends: module 
...

[nickolay-kondratyev]

Don't have a preferred number in mind right now.

[nickolay-kondratyev]

Its just that without headers being indexed by look up splitting things out is the main way to gain easy discoverability of information right now. (Besides doing inside file search, also brings up a question whether there are VSCode extension that improve search inside files, like allowing non ordered searches of keywords)

[kevinslin]

I think supporting headers with lookup makes sense - caveat being, should be after october (avoid new features this month) and also - we need to figure out how to represent this in the UI (quickinput component doesn't do previews and we would want to preview header results somewhere)

[kevinslin]

The goal with this schema - any developer that is familiar with this schema should be able to know where to go to get documentation on working with the code base (it could be that the documentation doesn't exist but at least, they would know its not there vs being buried somewhere else)

[kevinslin]

Some areas to expand on:

• are there common developer operations that are missing in the current schema?
• are there components that seem ambiguous?
• what else could we add/remove?

[nickolay-kondratyev]

Should we move

     test

To dev from qa?

[kevinslin]

there's a case for test to be in either place. dev since writing tests is part of development process but qa because having tests is part of quality insurance. unless you feel strongly that it belongs under dev, I would bias towards the present organization