From 6a0f2418c97896148be49ad1643bf11abb667714 Mon Sep 17 00:00:00 2001 From: Naveen MR Date: Tue, 20 Sep 2022 20:40:31 +0100 Subject: [PATCH] chore: refining docs --- .../en/engineering/builds-and-releases.md | 129 ++++++++++++++++-- .../engineering/{unit-test.md => testing.md} | 45 ++++-- .../content/en/engineering/translation.md | 40 ++---- 3 files changed, 160 insertions(+), 54 deletions(-) rename packages/noco-docs/content/en/engineering/{unit-test.md => testing.md} (91%) diff --git a/packages/noco-docs/content/en/engineering/builds-and-releases.md b/packages/noco-docs/content/en/engineering/builds-and-releases.md index 3696a5ea70..93273cd0e8 100644 --- a/packages/noco-docs/content/en/engineering/builds-and-releases.md +++ b/packages/noco-docs/content/en/engineering/builds-and-releases.md @@ -1,33 +1,129 @@ --- -title: "Build on Pull Requests" +title: "Releases & Builds" description: "NocoDB creates Docker and Binaries for each PR" -position: 3250 +position: 3300 category: "Engineering" -menuTitle: "Build on Pull Requests" +menuTitle: "Releases & Builds" --- +## Builds of NocoDB +There are 3 kinds of docker builds in NocoDB +- Release builds [nocodb/nocodb](https://hub.docker.com/r/nocodb/nocodb) : built during NocoDB release. +- Daily builds [nocodb/nocodb-daily](https://hub.docker.com/r/nocodb/nocodb-daily) : built every 6 hours from Develop branch. +- Daily builds [nocodb/nocodb-timely](https://hub.docker.com/r/nocodb/nocodb-timely): built for every PR. -NocoDB creates Docker and Binaries for each PR. +Below is an overview of how to make these builds and what happens behind the scenes. + +## Release builds + +### How to make a release build ? + +- Click [NocoDB release action](https://github.com/nocodb/nocodb/actions/workflows/release-nocodb.yml) +- You should see the below screen + + ![image](https://user-images.githubusercontent.com/35857179/167240353-a02f690f-c865-4ade-8645-64382405c9ea.png) +- Change `Use workflow from` to `Branch: master`. If you choose the wrong branch, the workflow will be ended. + + ![image](https://user-images.githubusercontent.com/35857179/167240383-dda05f76-8323-4f4a-b3e7-9db886dbd68d.png) +- Then there would be two cases - you can either leave target tag and pervious tag blank or manually input some values + +> Target Tag means the target deployment version, while Previous Tag means the latest version as of now. Previous Tag is used for Release Note only - showing the file / commit differences between two tags. + +### Case 1: Leaving inputs blank + +- If Previous Tag is blank, then the value will be fetched from [latest](https://github.com/nocodb/nocodb/releases/latest) +- If Target Tag is blank, then the value will be Previous Tag plus one. Example: 0.90.11 (Previous Tag) + 1 = 0.90.12 (Target Tag) + +### Case 2: Manually Input + +Why? Sometimes we may mess up in NPM deployment. As NPM doesn't allow us to redeploy to the same tag again, in this case we cannot just use the previous tag + 1. Therefore, we need to use previous tag + 2 instead and we manually configure it. + +- After that, click `Run workflow` to start +- You can see Summary for the overall job status. +- Once `release-draft-note` and `release-executables` is finished, then go to [releases](https://github.com/nocodb/nocodb/releases), edit the draft note and save as draft for time being. + - Example: Adding header, update content if necessary, and click `Auto-generate release notes` to include more info. +- Once `release-docker` is finished, then test it locally first. You'll be expected to see `Upgrade Available` notification in UI as we haven't published the release note. (the version is retrieved from there) +- Once everything is finished, then publish the release note and the deployment is considered as DONE. + +### How does release action work ? + +#### validate-branch + +To check if `github.ref` is master. Otherwise, other branches will be not accepted. + +#### process-input + +To enrich target tag or previous tag if necessary. + +#### pr-to-master + +Automate a PR from develop to master branch so that we know the actual differences between the previous tag and the current tag. We choose master branch for a deployment base. + +#### release-npm + +Build frontend and backend and release them to NPM. The changes during built such as version bumping will be committed and pushed to a temporary branch and an automated PR will be created and merged to master branch. + +Note that once you publish with a certain tag, you cannot publish with the same tag again. + +#### release-draft-note + +Generate a draft release note. Some actions need to be done after this step. + +#### release-docker + +Build docker image and publish it to Docker Hub. It may take around 15 - 30 mins. + +#### close-issues + +Open issues marked with label `Status: Fixed` and `Status: Resolved` will be closed by bot automatically with comment mentioning the fix is included in which version. + +Example: + +![image](https://user-images.githubusercontent.com/35857179/167241574-f8f7061f-c689-444a-b761-0a727974c53f.png) + +#### publish-docs + +Publish Documentations + +#### update-sdk-path + +`nocodb-sdk` is used in frontend and backend. However, in develop branch, the value would be `file:../nocodb-sdk` for development purpose (so that the changes done in nocodb-sdk in develop will be included in frontend and backend). During the deployment, the value will be changed to the target tag. This job is to update them back. + +#### sync-to-develop + +Once the deployment is finished, there would be some new changes being pushed to master branch. This job is to sync the changes back to develop so that both branch won't have any difference. + +## Daily builds + +### What are daily builds ? +- NocoDB creates every 6 hours from develop branches and publishes as nocodb/nocodb-daily +- This is so that we can easily try what is in the develop branch easily. + +### Docker images +- The docker images will be built and pushed to Docker Hub (See [nocodb/nocodb-daily](https://hub.docker.com/r/nocodb/nocodb-daily/tags) for the full list). + +## Timely builds + +### What are timely builds ? +NocoDB creates docker and binaries for each PR! This is to - reduce pull request cycle time - allow issue reporters / reviewers to verify the fix without setting up their local machines -## Docker - +### Docker images When a non-draft Pull Request is created, reopened or synchronized, a timely build for Docker would be triggered for the changes only included in the following paths. - - `packages/nocodb-sdk/**` - `packages/nc-gui/**` - `packages/nc-plugin/**` - `packages/nocodb/**` -The docker images will be built and pushed to Docker Hub (See [nocodb/nocodb-timely](https://hub.docker.com/r/nocodb/nocodb-timely/tags) for the full list). Once the image is ready, Github bot will add a comment with the command in the pull request. The tag would be `-pr---`. +The docker images will be built and pushed to Docker Hub (See [nocodb/nocodb-timely](https://hub.docker.com/r/nocodb/nocodb-timely/tags) for the full list). Once the image is ready, Github bot will add a comment with the command in the pull request. The tag would be `-pr---`. -![image](https://user-images.githubusercontent.com/35857179/178413534-84b29afb-7a52-437b-a5df-b842b397390b.png) +![image](https://user-images.githubusercontent.com/35857179/175012097-240dab05-da93-4c4e-87c1-1c36fb1350bd.png) -## Executables +## Executables or Binariess -Similarly, we provide a timely build for executables for non-docker users. The source code will be built, packaged as binary files, and pushed to Github (See [nocodb/nocodb-timely](https://github.com/nocodb/nocodb-timely/releases) for the full list). +Similarly, we provide a timely build for executables for non-docker users. The source code will be built, packaged as binary files, and pushed to Github (See [nocodb/nocodb-timely](https://github.com/nocodb/nocodb-timely/releases) for the full list). Currently, we only support the following targets: @@ -38,6 +134,13 @@ Currently, we only support the following targets: - `node16-macos-x64` - `node16-win-x64` -Once the executables are ready, Github bot will add a comment with the commands in the pull request. +Once the executables are ready, Github bot will add a comment with the commands in the pull request. + +![image](https://user-images.githubusercontent.com/35857179/175012070-f5f3e7b8-6dc5-4d1c-9f7e-654bc5039521.png) + +NocoDB creates Docker and Binaries for each PR. + +This is to +- reduce pull request cycle time +- allow issue reporters / reviewers to verify the fix without setting up their local machines -![image](https://user-images.githubusercontent.com/35857179/175012070-f5f3e7b8-6dc5-4d1c-9f7e-654bc5039521.png) \ No newline at end of file diff --git a/packages/noco-docs/content/en/engineering/unit-test.md b/packages/noco-docs/content/en/engineering/testing.md similarity index 91% rename from packages/noco-docs/content/en/engineering/unit-test.md rename to packages/noco-docs/content/en/engineering/testing.md index 7861530dea..0111ad9e70 100644 --- a/packages/noco-docs/content/en/engineering/unit-test.md +++ b/packages/noco-docs/content/en/engineering/testing.md @@ -3,13 +3,15 @@ title: "Writing Tests" description: "Overview to testing" position: 3250 category: "Engineering" -menuTitle: "Tests" +menuTitle: "Testing" --- -## Pre-requisites +## API Tests + +### Pre-requisites - MySQL is preferrable - however we fallback to SQLite -## Setup +### Setup ``` cp scripts/.env.copy scripts/.env open scripts/.env @@ -21,22 +23,24 @@ open scripts/.env # `DB_PORT` : mysql port ``` -## How to run API tests +### Running tests ``` cd packages/nocodb npm run test:unit ``` -## Key points +### Notes + +#### Key points - All individual unit tests are independent of each other. We don't use any shared state between tests. - Test environment includes `sakila` sample database and any change to it by a test is reverted before running other tests. - While running unit tests, it tries to connect to mysql server running on `localhost:3306` with username `root` and password `password`(which can be configured) and if not found, it will use `sqlite` as a fallback, hence no requirement of any sql server to run tests. -## Walk through of writing a unit test +#### Walk through of writing a unit test We will create an `Table` test suite as an example. -### Configure test +##### Configure test We will configure `beforeEach` which is called before each test is executed. We will use `init` function from `nocodb/packages/tests/unit/init/index.ts`, which is a helper function which configures the test environment(i.e resetting state, etc.). @@ -60,7 +64,7 @@ beforeEach(async function () { }); ``` -### Test case +##### Test case We will use `it` function to create a test case. We will use `supertest` to make a request to the server. We use `expect`(`chai`) to assert the response. @@ -76,7 +80,7 @@ it('Get table list', async function () { }); ``` -### Integrating the new test suite +##### Integrating the new test suite We create a new file `table.test.ts` in `packages/nocodb/tests/unit/rest/tests` directory. @@ -120,7 +124,7 @@ export default function () { We can then import the `Table` test suite to `Rest` test suite in `packages/nocodb/tests/unit/rest/index.test.ts` file(`Rest` test suite is imported in the root test suite file which is `packages/nocodb/tests/unit/index.test.ts`). -## Running test +#### Running test To run tests, run `npm run test:unit` in `packages/nocodb` directory. @@ -130,7 +134,7 @@ To run tests, run `npm run test:unit` in `packages/nocodb` directory. it.only('Get table list', async () => { ``` -## Folder structure +#### Folder structure The root folder for unit tests is `packages/tests/unit` @@ -141,7 +145,7 @@ The root folder for unit tests is `packages/tests/unit` - `index.test.ts` is the root test suite file which imports all the test suites. - `TestDbMngr.ts` is a helper class to manage test databases (i.e. creating, dropping, etc.). -## Patterns to follow +#### Patterns to follow - **Factories** - Use factories for create/update/delete data. No data should be directly create/updated/deleted in the test. @@ -154,6 +158,21 @@ The root folder for unit tests is `packages/tests/unit` - Use one file per factory. -## Using sakila db +#### Using sakila db To use sakila db use `createSakilaProject` from `factory/project` to create a project. This project will be seeded with `sakila` tables. + + +## Cypress Tests + +### Pre-requisites +> TODO + +### Setup +> TODO + +### Running tests +> TODO + +### Notes +> TODO \ No newline at end of file diff --git a/packages/noco-docs/content/en/engineering/translation.md b/packages/noco-docs/content/en/engineering/translation.md index e88c5be891..604594f499 100644 --- a/packages/noco-docs/content/en/engineering/translation.md +++ b/packages/noco-docs/content/en/engineering/translation.md @@ -6,12 +6,17 @@ category: "Engineering" menuTitle: "i18n translation" --- -NocoDB supports many foreign languages & community contributions are now simplified via [Crowdin](https://crowdin.com/) -Your help in fixing i18n goes a long way supporting NocoDB. Please follow below simple procedure to request corrections to existing translation errors. +- NocoDB supports 30+ foreign languages & community contributions are now simplified via [Crowdin](https://crowdin.com/). -# Public Contributions -### 1. How to add translation corrections (to existing languages)? +## How to add / edit translations ? + +### Using Github +- For English, make changes directly to [en.json](https://github.com/nocodb/nocodb/blob/develop/packages/nc-gui/lang/en.json) & commit to `develop` +- For any other language, use `crowdin` option. + + +### Using Crowdin - Setup [Crowdin](https://crowdin.com) account - Join [NocoDB](https://crowdin.com/project/nocodb) project @@ -33,10 +38,7 @@ Note: Crowdin provides translation recommendation's as in [4]. Click directly if ![Screenshot 2022-09-08 at 10 37 38 PM](https://user-images.githubusercontent.com/86527202/189184278-69d688ed-4e5a-4d5a-b629-9f6d10d79346.png) -A GitHub Pull Request will be automatically triggered (periodicity- 6 hours). We will follup on remaining integration work items. - ---- - +A GitHub Pull Request will be automatically triggered (periodicity- 6 hours). We will follow up on remaining integration work items. #### Reference @@ -45,26 +47,9 @@ Refer following articles to get additional details about Crowdin Portal usage - [Volunteer Translation Introduction](https://support.crowdin.com/for-volunteer-translators/) - [Online Editor](https://support.crowdin.com/online-editor/) ---- - -### 2. How to add a new language ? - -Your native language not in list, we will be glad to support with your help! Request for it [here](https://github.com/nocodb/nocodb/issues/new?assignees=dstala&labels=i18n+translation&template=i18n-translation-request.md&title=%5Bi18n%5D+Language+support+extension-+%3Clanguage+code%3E). We will be glad to take your help to set up translations - - ---- -# Engineering Contributions (for NocoDB developers & maintainers) - -> _This is exclusive to NocoDB developers & maintainers only_ - -### 1. Adding / Updating a string -### Add / update key-value - - [en] make changes directly to `en.json` & commit to `develop` - - [any other language] add changes using `crowdin` portal; procedure described below - -### Add a new language +## How to add a new language ? #### GitHub changes - Update enumeration in `enums.ts` [packages/nc-gui/lib/enums.ts] - Map JSON path in `a.i18n.ts` [packages/nc-gui/plugins/a.i18n.ts] @@ -80,9 +65,8 @@ Your native language not in list, we will be glad to support with your help! Req ![Screenshot 2022-09-08 at 10 54 04 PM](https://user-images.githubusercontent.com/86527202/189186632-0b9f5f55-0550-4d8f-a8ae-7e9b9076774e.png) ---- -### 2. String Categories +## String Categories - **General**: simple & common tokens (save, cancel, submit, open, close, home, and such) - **Objects**: objects from NocoDB POV (project, table, field, column, view, page, and such) - **Title**: screen headers (compact) (menu headers, modal headers)