Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: add mdBook based documentation #2

Merged
merged 3 commits into from
Jan 15, 2025
Merged

Conversation

yliang412
Copy link
Member

@yliang412 yliang412 commented Jan 14, 2025

Problem

We need to record our design and retain knowledge of the codebase as a team. Documentation is one of the best ways to do it.

Summary of changes

  • Check-in mdBook.
  • Add an initial overview that includes a wish list.
  • Add an initial glossary containing definitions and terms that optd developer will use.
  • Add a rfcs/ directory with a template.
  • Add a pull request template (in .github).

Future Work

  • Setup gh-pages for the documentation. It might conflict with the benchmark site. We will delay deploying mdBook to gh-pages once that a decision is made

Signed-off-by: Yuchen Liang <yuchenl3@andrew.cmu.edu>
@yliang412 yliang412 force-pushed the yuchen/initial-docs branch from 6a158cd to 61b2ac7 Compare January 14, 2025 13:37
@yliang412 yliang412 added the documentation Improvements or additions to documentation label Jan 14, 2025
Copy link
Member

@connortsui20 connortsui20 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: Instead of pointing out every place, is it possible to remove all trailing whitespace and make sure there are newlines at the end of files?

This isn't really that important, it's just that I have my IDE set up to scream at me every time one of those things happens 😄

docs/README.md Outdated Show resolved Hide resolved
yliang412 and others added 2 commits January 14, 2025 15:45
Signed-off-by: Yuchen Liang <yuchenl3@andrew.cmu.edu>
Copy link
Member

@connortsui20 connortsui20 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On thinking about this a bit more after @SarveshOO7 pointed this out, I think it would be good to distinguish between nodes and operators, especially considering we need to represent relations connected by pointers (in-memory) as well as connected via identifiers (on disk in the memo table).

Node: an in-memory node in a tree / DAG representing a relation / scalar
Operator: A representation of a relation / scalar that is not necessarily in memory

EDIT: OR

We could say everything that needs to be stored in the memo table is an expression (logical, physical, scalar expression), and then we say operators and nodes are purely in-memory (the initial input logical plan and final output physical plan are trees of operators / nodes)

I'm now in favor of the latter...

Could we maybe separate our the glossary from this PR?

@connortsui20
Copy link
Member

@yliang412
Copy link
Member Author

We can change the definitions. The main goal for this PR is to structure the docs directory.

@yliang412 yliang412 merged commit de96ad3 into main Jan 15, 2025
12 checks passed
@yliang412 yliang412 deleted the yuchen/initial-docs branch January 15, 2025 20:30
@yliang412 yliang412 self-assigned this Jan 17, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants