From 6a2010f9f03f8dc094a3d2c26b8346d91998b0f7 Mon Sep 17 00:00:00 2001 From: Florent Date: Wed, 14 Jun 2023 16:43:11 +0200 Subject: [PATCH] Add contribution guide #527 (#528) Co-authored-by: Florent --- .github/CONTRIBUTING.md | 8 +++ documentation/develop.md | 124 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 132 insertions(+) create mode 100644 .github/CONTRIBUTING.md create mode 100644 documentation/develop.md diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 00000000..471554fd --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,8 @@ +# Welcome to the contribution guide for Grist! + +You are eager to contribute to Grist? That's awesome! See below some contributions you can make: +- [translate](/documentation/translate.md) +- [write tutorials and user documentation](https://github.com/gristlabs/grist-help) +- [develop](/documentation/develop.md) +- [report issues or suggest enhancement](https://github.com/gristlabs/grist-core/issues/new) + diff --git a/documentation/develop.md b/documentation/develop.md new file mode 100644 index 00000000..a5b6f63b --- /dev/null +++ b/documentation/develop.md @@ -0,0 +1,124 @@ +# Development + +Please as a first start, tell the community about your intent to develop a feature or fix a bug. Search for the associated issue if it exists or open one with steps to reproduce (for bugs) or a [user story](https://en.wikipedia.org/wiki/User_story#Principle) (for features). + +## Setup + +### Prerequisites + +To setup your environment, you would need to install the following dependencies: + - git + - [nvm](https://github.com/nvm-sh/nvm/blob/master/README.md) (recommended) or nodejs installed on your system + - Chromium to run the end-to-end tests + - Python (preferably Python 3.9) and virtualenv + - :warning: As of 2023-06-06, Python 3.11 is not supported due to the version of the [wrapt dependency](https://github.com/GrahamDumpleton/wrapt/issues/196) + +### Clone the repository + +```bash +$ git clone https://github.com/gristlabs/grist-core +``` + +And then, enter the grist-core root directory: + +```bash +$ cd grist-core/ +``` + +### Setup nodejs + +#### Using nvm (recommanded) + +You need to install the supported nodejs version as well as yarn. To do so, in the grist-core root directory, run the following command to install nodejs via nvm: + +```bash +$ nvm install +``` + +Now check that node is installed in the version specified in the `.nvmrc` file: + +```bash +$ node --version +``` + +Then install yarn (the `-g` flag here means that yarn will be available globally): +```bash +$ npm install -g yarn +``` + +Now each time you want to load nodejs and yarn in your environment, just run the following command at grist-core root directory: + +```bash +$ nvm use +``` + +#### Using nodejs + +You can also use nodejs installed in your system. To prevent incompatibilities, ensure that the `node --version` command reports a version equal or greater to the one in `.nvmrc`. + +### Install the python packages + +Be sure to have Python and virtualenv installed. On debian-based Linux distributions, you can simply run the following command as root: + +```bash +# apt install python3.9 python3.9-venv +``` + +### Install the project dependencies and build + +First install the nodejs dependencies: + +```bash +$ yarn install +``` + +Then prepare the virtual environment with all the python dependencies: + +```bash +$ yarn install:python +``` + +Finally run this to do an initial build: + +```bash +$ yarn run build:prod +``` + +## Start the server in development mode + +Just run the following command: +```bash +$ yarn start +``` + +Each time you change something, just reload the webpage in your browser. + +Happy coding! + +### Pick an issue + +Lost on what you can do to help? If you are new to Grist, you may just pick one of the issues labelled `good first issue`: + +https://github.com/gristlabs/grist-core/labels/good%20first%20issue + +## Run tests + +You may run the tests using one of these commands: + - `yarn test` to run all the tests + - `yarn test:smoke` to run the minimal test checking Grist can open, create and edit a document + - `yarn test:nbrowser` to run the end-to-end tests + - `yarn test:client` to run the tests for the client libraries + - `yarn test:common` to run the tests for the common libraries shared between the client and the server + - `yarn test:server` to run the backend tests + - `yarn test:docker` to run some end-to-end tests under docker + - `yarn test:python` to run the data engine tests + +## Develop widgets + +Check out this repository: https://github.com/gristlabs/grist-widget#readme + +## Documentation + +Some documentation to help you starting developing: + - [Grainjs](https://github.com/gristlabs/grainjs/) (The library used to build the DOM) + - [The user support documentation](https://support.getgrist.com/)