Add and document mise (asdf clone) to enable reproducible environment for the project

.github/workflows/test.yml

@@ -6,11 +6,11 @@ jobs:
   test:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
-      - uses: actions/setup-node@v3
+      - uses: actions/setup-node@v4
         with:
-          node-version: 16
+          node-version-file: .tool-versions
           cache: yarn
 
       - run: yarn install --frozen-lockfile
@@ -19,11 +19,11 @@ jobs:
   build-minimal:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
-      - uses: actions/setup-node@v3
+      - uses: actions/setup-node@v4
         with:
-          node-version: 16
+          node-version-file: .tool-versions
           cache: yarn
 
       - run: yarn install --frozen-lockfile
@@ -37,11 +37,11 @@ jobs:
   build-full:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
-      - uses: actions/setup-node@v3
+      - uses: actions/setup-node@v4
         with:
-          node-version: 16
+          node-version-file: .tool-versions
           cache: yarn
 
       - run: yarn install --frozen-lockfile
@@ -57,11 +57,11 @@ jobs:
   # build-full-official-api:
   #   runs-on: ubuntu-latest
   #   steps:
-  #     - uses: actions/checkout@v3
+  #     - uses: actions/checkout@v4
 
-  #     - uses: actions/setup-node@v3
+  #     - uses: actions/setup-node@v4
   #       with:
-  #         node-version: 16
+  #         node-version-file: .tool-versions
   #         cache: yarn
 
   #     - run: yarn install --frozen-lockfile

.mise.toml

@@ -0,0 +1,19 @@
+[tools]
+# node-gyp has issues with newer python versions:
+# 'ValueError: invalid mode: 'rU' while trying to load binding.gyp'
+# These should be fixed by downgrading python to 3.10
+# Source: https://stackoverflow.com/a/74732671
+python = ['3.10']
+
+# Node 20.X breaks the node-gyp module:
+# TypeError: Cannot assign to read only property 'cflags' of object '#<Object>'
+# See more: https://stackoverflow.com/a/77910474/1337062
+# Node 18.X breaks ava test runner doesn't seem to work in package/notion-utils tests
+# node = ['16']
+# We read this value from .tool-versions file instead
+
+# Installing with npm doesn't seem to work out, use yarn everywhere
+"npm:yarn" = "latest"
+
+# To be able to build the packages in the monorepo workspace
+"npm:lerna" = "^4.0.0"

.tool-versions

@@ -0,0 +1,7 @@
+# FIXME: Remove this file when actions/setup-node supports .mise.toml
+# See more: https://github.com/actions/setup-node/issues/787
+nodejs 16.20.2
+
+# node-gyp has issues with newer python versions.
+# This is the latest version of 3.10.x as of October 2024
+python 3.10.13

contributing.md

@@ -3,10 +3,31 @@
 Suggestions and pull requests are highly encouraged. Have a look at the [open issues](https://github.com/NotionX/react-notion-x/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22+sort%3Areactions-%2B1-desc), especially [the easy ones](https://github.com/NotionX/react-notion-x/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22+sort%3Areactions-%2B1-desc).
 
 ## Development
+### Installing and using mise
+This project has a few aging dependencies like `node-gyp` and `lerna`.
 
-To develop the project locally, you'll need a recent version of Node.js and `yarn` v1 installed globally.
+Getting the project up and running was a bit hard so we defined the environment using [mise](https://github.com/jdx/mise). Mise is a tool like `nvm` or `asdf` and allows locking up both `python` and `nodejs` versions and ensures you have `yarn` installed as well.
 
-To get started, clone the repo and run `yarn` from the root directory:
+We would love to see contributions which would help updating the aging dependencies ❤️.
+
+If you are using MacOS you can install mise with `homebrew`:
+```sh
+brew install mise
+```
+Otherwise please check [mise installation docs](https://mise.jdx.dev/getting-started.html).
+
+Then activate mise. This depends on your shell. You can either run one of the following or copy them to your shell configs:
+```sh
+# Bash
+eval "$(mise activate bash)"
+# ZSH
+eval "$(mise activate zsh)"
+# Fish
+mise activate fish | source
+```
+
+### Cloning the repo and installing packages
+After installing `mise` you can proceed to clone the repo and run `yarn` from the root directory:
 
 ```bash
 git clone https://github.com/NotionX/react-notion-x.git