From 889503d1cc3d1f568a1058ce9ab5f1346d73f2a4 Mon Sep 17 00:00:00 2001 From: Himself65 Date: Sat, 8 Apr 2023 16:33:58 -0500 Subject: [PATCH] docs: add contributing tutorial (#1851) --- README.md | 5 ++ docs/contributing/bump-blocksuite.md | 32 ------------ docs/contributing/tutorial.md | 77 ++++++++++++++++++++++++++++ 3 files changed, 82 insertions(+), 32 deletions(-) delete mode 100644 docs/contributing/bump-blocksuite.md create mode 100644 docs/contributing/tutorial.md diff --git a/README.md b/README.md index 0e15892a3a..fa0923cfa4 100644 --- a/README.md +++ b/README.md @@ -214,6 +214,11 @@ For feature request please see [community.affine.pro](https://community.affine.p See [BUILDING.md] for instructions on how to build AFFiNE from source code. +## Contributing + +We welcome contributions from everyone. +See [docs/contributing/tutorial.md](./docs/contributing/tutorial.md) for details. + ## License See [LICENSE] for details. diff --git a/docs/contributing/bump-blocksuite.md b/docs/contributing/bump-blocksuite.md deleted file mode 100644 index 9e0122ebf1..0000000000 --- a/docs/contributing/bump-blocksuite.md +++ /dev/null @@ -1,32 +0,0 @@ -# Bump Blocksuite - -```shell -pnpm update:core -``` - -## Understand the version number - -### Stable - -You can see all the stable version tags [here](https://github.com/toeverything/blocksuite/tags). - -### Nightly - -If it's nightly version, the version will follow `${version}-${date}-${hash}`. - -For example, `0.4.0-20230203030233-b22bea7` means that -the version is based on `0.4.0`, the building date is `20230203030233`, -and the commit hash is `b22bea7`. - -> For the source code, see [here](https://github.com/toeverything/set-build-version/blob/master/src/version.ts) - -Using this version format, you can easily check the diff between each version. - -For example, the diff from old version `0.4.0-20230201063624-4e0463b` to new version `0.4.0-20230203030233-b22bea7` -is . - -## Fix the breaking change - -You can follow this file to keep updated: - -https://github.com/toeverything/blocksuite/blob/master/packages/playground/src/main.ts diff --git a/docs/contributing/tutorial.md b/docs/contributing/tutorial.md new file mode 100644 index 0000000000..8b51f4bc5a --- /dev/null +++ b/docs/contributing/tutorial.md @@ -0,0 +1,77 @@ +# Tutorial + +## Introduction + +This tutorial will walk you through the codebase of AFFiNE. It is intended for new contributors to AFFiNE. + +## Building the project + +Make sure you know how to build the project. See [BUILDING](../BUILDING.md) for more information. + +For the debugging purpose, you might need use local OctoBase on port 3000. + +## Codebase overview + +The codebase is organized as follows: + +- `apps/` contains the source code for the different entry points of the project. + - `web/` contains the source code for the web app. + - `electron/` contains the source code for the Electron app. + - `server/` backend side for AFFiNE, see instead. +- `packages/` contains the source code for all the packages in the repo. + - `cli` contains the source code for the CLI. Development only. + - `component` contains the source code for the UI component library. + - `debug` contains the source code for the debug helper. + - `env` contains the source code for the environment setup. + - `hooks` contains the source code for the custom React hooks. + - `i18n` contains the source code for the internationalization. + - `jotai` contains the source code for the Jotai store atoms. + - `octobase-node` contains the source code for the OctoBase Node.js binding using Rust. + - `templates` contains the source code for the templates. + - `workspace` contains the source code for the workspace related code. + +### `@affine/env` + +Environment setup for AFFiNE client side. + +It includes the global constants, browser and system check. + +This package should be imported at the very beginning of the entry point. + +### `@affine/workspace` + +Current we have two workspace plugin: + +- `local` for local workspace, which is the default workspace type. +- `affine` for cloud workspace, which is the workspace type for AFFiNE Cloud with OctoBase backend. + +#### Design principles + +- Each workspace plugin has its state and is isolated from other workspace plugins. +- The workspace plugin is responsible for its own state management, data persistence, synchronization, data backup and recovery. + +For the workspace API, see [types.ts](../../packages/workspace/src/type.ts). + +### `@affine/component` + +The UI component library for AFFiNE. + +Each component should be a standalone component which can be used in any context, like the Storybook. + +## Debugging Environments + +### `@affine/env` + +```shell +yarn dev +``` + +### `@affine/electron` + +See [building desktop client app](../building-desktop-client-app.md). + +### `@affine/component` Storybook + +```shell +yarn workspace @affine/component storybook +```