docs: update outdated docs (toeverything#6756)

fix toeverything#5171

.github/workflows/build-test.yml

@@ -546,7 +546,6 @@ jobs:
         run: yarn workspace @affine/electron make --platform=linux --arch=x64
         if: ${{ matrix.spec.target == 'x86_64-unknown-linux-gnu' }}
         env:
-          SKIP_PLUGIN_BUILD: 1
           SKIP_WEB_BUILD: 1
           HOIST_NODE_MODULES: 1
 

.github/workflows/release-desktop.yml

@@ -57,7 +57,6 @@ jobs:
           SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
           SENTRY_DSN: ${{ secrets.SENTRY_DSN }}
           RELEASE_VERSION: ${{ steps.version.outputs.APP_VERSION }}
-          SKIP_PLUGIN_BUILD: 'true'
           SKIP_NX_CACHE: 'true'
           MIXPANEL_TOKEN: ${{ secrets.MIXPANEL_TOKEN }}
 
@@ -138,7 +137,6 @@ jobs:
       - name: make
         run: yarn workspace @affine/electron make --platform=${{ matrix.spec.platform }} --arch=${{ matrix.spec.arch }}
         env:
-          SKIP_PLUGIN_BUILD: 1
           SKIP_WEB_BUILD: 1
           HOIST_NODE_MODULES: 1
 
@@ -214,7 +212,6 @@ jobs:
       - name: package
         run: yarn workspace @affine/electron package --platform=${{ matrix.spec.platform }} --arch=${{ matrix.spec.arch }}
         env:
-          SKIP_PLUGIN_BUILD: 1
           SKIP_WEB_BUILD: 1
           HOIST_NODE_MODULES: 1
 

docs/BUILDING.md

@@ -2,7 +2,7 @@
 
 > **Warning**:
 >
-> This document has not been updated for a while.
+> This document is not guaranteed to be up-to-date.
 > If you find any outdated information, please feel free to open an issue or submit a PR.
 
 > **Note**
@@ -27,7 +27,7 @@ We suggest develop our product under node.js LTS(Long-term support) version
 
 install [Node LTS version](https://nodejs.org/en/download)
 
-> Up to now, the major node.js version is 18.x
+> Up to now, the major node.js version is 20.x
 
 #### Option 2: Use node version manager
 
@@ -76,7 +76,7 @@ Once Developer Mode is enabled, execute the following command with administrator
 ```sh
 # Enable symbolic links
 git config --global core.symlinks true
-# Clone the repository, also need to be run with administrator privileges
+# Clone the repository
 git clone https://github.com/toeverything/AFFiNE
 ```
 

docs/CONTRIBUTING.md

@@ -1,93 +1 @@
-# Welcome to our contributing guide <!-- omit in toc -->
-
-Thank you for investing your time in contributing to our project! Any contribution you make will be reflected on our GitHub :sparkles:.
-
-Read our [Code of Conduct](./CODE_OF_CONDUCT.md) to keep our community approachable and respectable. Join our [Discord](https://discord.com/invite/yz6tGVsf5p) server for more.
-
-In this guide you will get an overview of the contribution workflow from opening an issue, creating a PR, reviewing, and merging the PR.
-
-Use the table of contents icon on the top left corner of this document to get to a specific section of this guide quickly.
-
-## New contributor guide
-
-Currently we have two versions of AFFiNE:
-
-- [AFFiNE Pre-Alpha](https://livedemo.affine.pro/). This version uses the branch `Pre-Alpha`, it is no longer actively developed but contains some different functions and features.
-- [AFFiNE Alpha](https://pathfinder.affine.pro/). This version uses the `canary` branch, this is the latest version under active development.
-
-To get an overview of the project, read the [README](../README.md). Here are some resources to help you get started with open source contributions:
-
-- [Finding ways to contribute to open source on GitHub](https://docs.github.com/en/get-started/exploring-projects-on-github/finding-ways-to-contribute-to-open-source-on-github)
-- [Set up Git](https://docs.github.com/en/get-started/quickstart/set-up-git)
-- [GitHub flow](https://docs.github.com/en/get-started/quickstart/github-flow)
-- [Collaborating with pull requests](https://docs.github.com/en/github/collaborating-with-pull-requests)
-
-## Getting started
-
-Check to see what [types of contributions](types-of-contributions.md) we accept before making changes. Some of them don't even require writing a single line of code :sparkles:.
-
-### Issues
-
-#### Create a new issue or feature request
-
-If you spot a problem, [search if an issue already exists](https://docs.github.com/en/github/searching-for-information-on-github/searching-on-github/searching-issues-and-pull-requests#search-by-the-title-body-or-comments). If a related issue doesn't exist, you can open a new issue using a relevant [issue form](https://github.com/toeverything/AFFiNE/issues/new/choose).
-
-#### Solve an issue
-
-Scan through our [existing issues](https://github.com/toeverything/AFFiNE/issues) to find one that interests you. You can narrow down the search using `labels` as filters. See our [Labels](https://github.com/toeverything/AFFiNE/labels) for more information. As a general rule, we don’t assign issues to anyone. If you find an issue to work on, you are welcome to open a PR with a fix.
-
-### Make Changes
-
-#### Make changes in the UI
-
-Click **Make a contribution** at the bottom of any docs page to make small changes such as a typo, sentence fix, or a broken link. This takes you to the `.md` file where you can make your changes and [create a pull request](#pull-request) for a review.
-
-#### Make changes in a codespace
-
-For more information about using a codespace for working on GitHub documentation, see "[Working in a codespace](https://github.com/github/docs/blob/main/contributing/codespace.md)."
-
-#### Make changes locally
-
-1. [Install Git LFS](https://docs.github.com/en/github/managing-large-files/versioning-large-files/installing-git-large-file-storage).
-
-2. Fork the repository.
-
-- Using GitHub Desktop:
-
-  - [Getting started with GitHub Desktop](https://docs.github.com/en/desktop/installing-and-configuring-github-desktop/getting-started-with-github-desktop) will guide you through setting up Desktop.
-  - Once Desktop is set up, you can use it to [fork the repo](https://docs.github.com/en/desktop/contributing-and-collaborating-using-github-desktop/cloning-and-forking-repositories-from-github-desktop)!
-
-- Using the command line:
-  - [Fork the repo](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo#fork-an-example-repository) so that you can make your changes without affecting the original project until you're ready to merge them.
-
-3. Install or update to **Node.js v16**.
-
-4. Create a working branch and start with your changes!
-
-### Commit your update
-
-Commit the changes once you are happy with them.
-
-Reach out the community members for necessary help.
-
-Once your changes are ready, don't forget to self-review to speed up the review process:zap:.
-
-### Pull Request
-
-When you're finished with the changes, create a pull request, also known as a PR.
-
-- Fill the "Ready for review" template so that we can review your PR. This template helps reviewers understand your changes as well as the purpose of your pull request.
-- Don't forget to [link PR to issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue) if you are solving one.
-- Enable the checkbox to [allow maintainer edits](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/allowing-changes-to-a-pull-request-branch-created-from-a-fork) so the branch can be updated for a merge.
-  Once you submit your PR, a Docs team member will review your proposal. We may ask questions or request for additional information.
-- We may ask for changes to be made before a PR can be merged, either using [suggested changes](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/incorporating-feedback-in-your-pull-request) or pull request comments. You can apply suggested changes directly through the UI. You can make any other changes in your fork, then commit them to your branch.
-- As you update your PR and apply changes, mark each conversation as [resolved](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/commenting-on-a-pull-request#resolving-conversations).
-- If you run into any merge issues, checkout this [git tutorial](https://github.com/skills/resolve-merge-conflicts) to help you resolve merge conflicts and other issues.
-
-### Your PR is merged!
-
-Congratulations :tada::tada: The AFFiNE team thanks you :sparkles:.
-
-Once your PR is merged, your contributions will be publicly visible on our GitHub.
-
-Now that you are part of the AFFiNE community, see how else you can join and help over at [GitBook](https://docs.affine.pro/affine/)
+# Please visit https://docs.affine.pro/docs/contributing

docs/building-desktop-client-app.md

@@ -1,41 +1,111 @@
 # Building AFFiNE Desktop Client App
 
+> **Warning**:
+>
+> This document is not guaranteed to be up-to-date.
+> If you find any outdated information, please feel free to open an issue or submit a PR.
+
 ## Table of Contents
 
 - [Prerequisites](#prerequisites)
 - [Development](#development)
 - [Build](#build)
 - [CI](#ci)
 
+## Things you may need to know before getting started
+
+Building the desktop client app for the moment is a bit more complicated than building the web app. The client right now is an Electron app that wraps the prebuilt web app, with parts of the native modules written in Rust, which means we have the following source modules to build a desktop client app:
+
+1. `packages/frontend/core`: the web app
+2. `packages/frontend/native`: the native modules written in Rust (mostly the sqlite bindings)
+3. `packages/frontend/electron`: the Electron app (containing main & helper process, and the electron entry point in `packages/frontend/electron/renderer`)
+
+#3 is dependent on #1 and #2, and relies on electron-forge to make the final app & installer. To get a deep understanding of how the desktop client app is built, you may want to read the workflow file in [release-desktop.yml](/.github/workflows/release-desktop.yml).
+
+Due to [some limitations of Electron builder](https://github.com/yarnpkg/berry/issues/4804), you may need to have two separate yarn config for building the core and the desktop client app:
+
+1. build frontend (with default yarn settings)
+2. build electron (reinstall with hoisting off)
+
+We will explain the steps in the following sections.
+
 ## Prerequisites
 
-Before you start building AFFiNE Desktop Client Application, please [install Rust toolchain first](https://www.rust-lang.org/learn/get-started).
+Before you start building AFFiNE Desktop Client Application, please following the same steps in [BUILDING#Prerequisites](./BUILDING.md#prerequisites) to install Node.js and Rust.
 
-Note that if you encounter any issues with installing Rust and crates, try following [this guide (zh-CN)](https://course.rs/first-try/slowly-downloading.html) to set up alternative registries.
+On Windows, you must enable symbolic links this code repo. See [#### Windows](./BUILDING.md#Windows).
 
-## Development
+## Build, package & make the desktop client app
 
-To run AFFiNE Desktop Client Application locally, run the following commands:
+### 0. Build the native modules
 
-```sh
-# in repo root
+Please refer to `Build Native Dependencies` section in [BUILDING.md](./BUILDING.md#Build-Native-Dependencies) to build the native modules.
+
+### 1. Build the core
+
+On Mac & Linux
+
+```shell
+BUILD_TYPE=canary SKIP_NX_CACHE=1 yarn workspace @affine/electron generate-assets
+```
+
+On Windows (powershell)
+
+```powershell
+$env:BUILD_TYPE="canary"
+$env:SKIP_NX_CACHE=1
+$env:DISTRIBUTION=desktop
+$env:SKIP_WEB_BUILD=1
+yarn build --skip-nx-cache
+```
+
+### 2. Re-config yarn, clean up the node_modules and reinstall the dependencies
+
+As we said before, you need to reinstall the dependencies with hoisting off. You can do this by running the following command:
+
+```shell
+yarn config set nmMode classic
+yarn config set nmHoistingLimits workspaces
+```
+
+Then, clean up all node_modules and reinstall the dependencies:
+
+On Mac & Linux
+
+```shell
+find . -name 'node_modules' -type d -prune -exec rm -rf '{}' +
 yarn install
-yarn dev
+```
 
-# in packages/frontend/native
-yarn build
+On Windows (powershell)
 
-# in packages/frontend/electron
-yarn dev
+```powershell
+dir -Path . -Filter node_modules -recurse | foreach {echo $_.fullname; rm -r -Force $_.fullname}
+yarn install
 ```
 
-Now you should see the Electron app window popping up shortly.
+### 3. Build the desktop client app installer
 
-## Build
+#### Mac & Linux
 
-To build the desktop client application, run `yarn make` in `packages/frontend/electron`.
+Note: you need to comment out `osxSign` and `osxNotarize` in `forge.config.js` to skip signing and notarizing the app.
+
+```shell
+BUILD_TYPE=canary SKIP_WEB_BUILD=1 HOIST_NODE_MODULES=1 yarn workspace @affine/electron make
+```
 
-Note: you may want to comment out `osxSign` and `osxNotarize` in `forge.config.js` to avoid signing and notarizing the app.
+#### Windows
+
+Making the windows installer is a bit different. Right now we provide two installer options: squirrel and nsis.
+
+```powershell
+$env:BUILD_TYPE="canary"
+$env:SKIP_WEB_BUILD=1
+$env:HOIST_NODE_MODULES=1
+yarn workspace @affine/electron package
+yarn workspace @affine/electron make-squirrel
+yarn workspace @affine/electron make-nsis
+```
 
 Once the build is complete, you can find the paths to the binaries in the terminal output.