From d3819f63bfd758fc9fb7c6d13be12525a920c19e Mon Sep 17 00:00:00 2001 From: M <120020483+VWSCoronaDashboard30@users.noreply.github.com> Date: Fri, 10 May 2024 14:25:33 +0200 Subject: [PATCH] task(README): Updated README files (#5022) * task(README): Updated README files * task(README): PR comment resolution * task(README): PR comment resolution --- README.md | 19 ++++++----- docs/developers.md | 4 ++- docs/index.md | 2 +- docs/lokalize-texts.md | 66 +++++++++++++++++++++++++-------------- docs/page-parts.md | 42 ++++++++++++------------- docs/release-procedure.md | 4 ++- docs/styled-system.md | 2 +- docs/timeline-events.md | 2 +- packages/app/README.md | 22 ++++++++----- packages/cms/README.md | 2 +- 10 files changed, 99 insertions(+), 66 deletions(-) diff --git a/README.md b/README.md index a3cdc7ba84..865c62647d 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,6 @@ -# NL Coronavirus Dashboard +# Archived NL Coronavirus Dashboard + +` As of 02-04-2024, the Coronadashboard has been brought offline, so some of the sections are not relevant anymore.` The dashboard provides information on the outbreak and prevalence of COVID-19 in The Netherlands. It combines measured and modelled data from various sources to @@ -6,17 +8,20 @@ give a broad perspective on the subject. ## Contact -If you want to contact the dashboard team, feel free to open an issue for +` As of 02-04-2024, the Coronadashboard has been brought offline. This section is not applicable anymore.` + +~~If you want to contact the dashboard team, feel free to open an issue for technical questions, bug reports, or security findings. If you have a generic question or remark about the -corona policy of the Dutch government, please consult the [frequently asked questions](https://coronadashboard.rijksoverheid.nl/veelgestelde-vragen) or [contact page](https://coronadashboard.rijksoverheid.nl/contact) on the dashboard. +corona policy of the Dutch government, please consult the [frequently asked questions](https://coronadashboard.rijksoverheid.nl/veelgestelde-vragen) or [contact page](https://coronadashboard.rijksoverheid.nl/contact) on the dashboard.~~ ## Development & Contribution process -The core team works directly from this open-source repository. If you plan to +` As of 02-04-2024, the Coronadashboard has been brought offline. This section is not applicable anymore.` + +~~The core team works directly from this open-source repository. If you plan to propose changes, we recommend opening an issue beforehand where we can discuss your planned changes. This increases the chance that we might be able to use -your contribution (or it avoids doing work if there are reasons why we wouldn't -be able to use it). +your contribution (or it avoids doing work if there are reasons why we wouldn't be able to use it).~~ ## Packages @@ -47,7 +52,7 @@ $ yarn dev In this project, we use Yarn instead of NPM, so the documentation assumes you have the `yarn` executable installed on your system. -If you would like to run the code on your local machine check out the readme +If you would like to run the code on your local machine check out the README documentation of the [app](/packages/app/README.md) and (optionally the) [cms](/packages/cms/README.md) packages. diff --git a/docs/developers.md b/docs/developers.md index 2226ae2f36..2eb509aad4 100644 --- a/docs/developers.md +++ b/docs/developers.md @@ -2,7 +2,9 @@ ## Shortcut scripts -The monorepo contains projects which the developer can access with shortcut scripts at the root of the project. Instead of writing the path in the CLI like `yarn workspace @corona-dashboard cms lokalize:import`, we can access the script by writing `yarn cms:lokalize-import` to bring your local JSON files up-to-date with the Sanity dataset. Another example is using `yarn build:app` instead of `yarn workspace @corona-dashboard/app build` to make a build during the release procedure. Lastly, running `yarn check-all` will make sure the code, data and tests work as expected, instead of running scripts individually. +` As of 02-04-2024, the Coronadashboard has been brought offline. Some parts of this section are not applicable anymore.` + +~~The monorepo contains projects which the developer can access with shortcut scripts at the root of the project. Instead of writing the path in the CLI like `yarn workspace @corona-dashboard cms lokalize:import`, we can access the script by writing `yarn cms:lokalize-import` to bring your local JSON files up-to-date with the Sanity dataset.~~ An example is using `yarn build:app` instead of `yarn workspace @corona-dashboard/app build` to make a build during the release procedure. Lastly, running `yarn check-all` will make sure the code, data and tests work as expected, instead of running scripts individually. Available shortcut scripts: diff --git a/docs/index.md b/docs/index.md index 0b1ff4939d..bbf291d603 100644 --- a/docs/index.md +++ b/docs/index.md @@ -2,7 +2,7 @@ ## Project -- [Release Procedure](release-procedure.md) +- ~~[Release Procedure](release-procedure.md)~~ ## Infrastructure diff --git a/docs/lokalize-texts.md b/docs/lokalize-texts.md index 7ff8989484..b6aed3b385 100644 --- a/docs/lokalize-texts.md +++ b/docs/lokalize-texts.md @@ -1,5 +1,7 @@ # Sanity & Lokalize Texts +` As of 02-04-2024, the Coronadashboard has been brought offline. Some parts of this section are not applicable anymore.` + This section describes some of the ins and outs around locale texts that we use to translate short-copy. These strings used to be managed by a tool called Lokalize. After a while we concluded that their application did not meet our @@ -22,27 +24,30 @@ In summary these are the most important things you should be aware of: - The `import` command brings your local JSON files up-to-date with the Sanity dataset. The TypeScript compiler will error when your JSON files do not contain all the texts which are referenced in the code. -- The JSON import contains document ids as part of the keys. You can make - changes locally to the **app/src/locale/nl_export.json** file. Add new keys, - delete them or rename and move existing ones. After you make changes run the +- The JSON import contains document ids as part of the keys. You can ONLY make + changes locally to the **app/src/locale/nl_export.json** or **app/src/locale/en_export.json** file. Add new keys, + delete them or rename and move existing ones. + ~~After you make changes run the `lokalize:apply-json-edits` script. This will give you a list of changes and you can decide which ones to apply. Changes are written in a mutation log file, and at the end the JSON is re-imported to reflect all changes. It is recommended to run `lokalize:apply-json-edits` after the feature has been finished, right before merging it to develop since during development - changes to the **nl_export.json** file might fluctuate. -- Merge conflicts in the mutations file are common, but **always** choose to + changes to the **nl_export.json** file might fluctuate.~~ +- ~~Merge conflicts in the mutations file are common, but **always** choose to **accept both changes**, so that you never remove any mutations. You do not have to worry about the order of the timestamps, as these mutations are sorted - before they are applied. -- When a feature branch gets merged into develop, the `sync-after-feature` + before they are applied.~~ +- The `sync-after-feature` script is not in use anymore. + ~~When a feature branch gets merged into develop, the `sync-after-feature` command runs which adds new texts to production so that the communication team - can prepare them for upcoming releases. -- After a release, we manually run the `sync-after-release`, which then strips + can prepare them for upcoming releases.~~ +- The `sync-after-release` procedure is applicable anymore. + ~~After a release, we manually run the `sync-after-release`, which then strips all keys from production that are not in use in development anymore. This also clears the mutations log file which should then be committed. **Do not delete texts from development between deploying the release and running the - `sync-after-release` command**. + `sync-after-release` command**.~~ ## Mutations File @@ -67,9 +72,10 @@ when resolving conflicts, so that none of the lines are ever deleted. The application reads its locale strings from **packages/app/public/nl_export.json** and **packages/app/public/en_export.json**. -These JSONs are imported from the Sanity lokalize documents, but they are not +These JSONs are imported from the Sanity lokalize documents, but the latest versions are available in the `develop` branch. The `export` files are immutable since the app is archived. +~~but they are not part of the repository. Therefore, you will regularly need to run `yarn lokalize:import` in -order to keep your local JSON file up-to-date with the Sanity dataset. +order to keep your local JSON file up-to-date with the Sanity dataset.~~ The JSONs will include Sanity document ids in every leaf-key which are used to detect add-/delete-/move-actions of texts (`some_key__@__{document_id}`). These @@ -113,7 +119,7 @@ and unflattens this list of paths into a JSON file. (The Dutch texts are seriali paths and saves those to Sanity. Obviously there is a bunch of logic involved that checks if a path is new or existing, but for those details we refer to the source code. -## How to Add, Delete or Move Texts +## **DEPRECATED** How to Add, Delete or Move Texts First make sure the JSONs include document ids (`some_key__@__{document_id}`). Run `yarn lokalize:import` if these are not yet present in your JSONs. @@ -122,17 +128,21 @@ You can add, delete and move keys by mutating the **nl_export.json** file. The sync script will automagically detect additions, deletions or moved lokalize texts. -After you're done with the changes run `yarn lokalize:apply-json-edits` and +~~After you're done with the changes run `yarn lokalize:apply-json-edits` and after confirmation all selected mutations will be written to the mutations log -file. +file.~~ + +~~New texts will only have an NL (Dutch) string when they are added and will use NL as a +fallback.~~ -New texts will only have an NL (Dutch) string when they are added and will use NL as a -fallback. +~~After syncing texts, the import script is called to update your local JSON file +and re-generate the SiteText type interface.~~ -After syncing texts, the import script is called to update your local JSON file -and re-generate the SiteText type interface. +The Sanity Lokalize dataset will remain immutable with the archival of the application. -### Delete/Move Mutations +### **DEPRECATED** Delete/Move Mutations + +` As of 02-04-2024, the Coronadashboard has been brought offline, so some sections of this chapter are no longer relevant.` Because feature branches plus the development deployment all use the same Sanity dataset, we can not simply remove a lokalize text document from the dataset @@ -153,7 +163,9 @@ documents. During sync-after-feature the move is finalized by changing the key and subject properties of the targeted document. This preserves the document history and drafts. -### Flow to Production +### **DEPRECATED** Flow to Production + +` As of 02-04-2024, the Coronadashboard has been brought offline, so this chapter is no longer relevant.` Texts are first added to the development dataset. When the feature branch gets merged, a GitHub action will inject any new texts into the production dataset @@ -162,7 +174,9 @@ and flag them as being new. The communication team is then able to see a list of newly added texts and prepare them for an upcoming release. -## Sync After Feature +## **DEPRECATED** Sync After Feature + +` As of 02-04-2024, the Coronadashboard has been brought offline, so this chapter is no longer relevant.` The `sync-after-feature` command is triggered automatically by a GitHub Action whenever a feature branch is merged to the develop branch. It contains the @@ -180,7 +194,9 @@ If the text additions of a feature branch get deleted after the branch was merged, those deletions will propagate to production after the release using the `sync-after-release` command. -## Sync After Release +## **DEPRECATED** Sync After Release + +` As of 02-04-2024, the Coronadashboard has been brought offline, so this chapter is no longer relevant.` The `sync-after-release` command should be triggered manually shortly after a release has been deployed to production. It can not really hurt to forget to run @@ -209,7 +225,9 @@ from development between deploying the release and running the `sync-after-release`. Because then those keys will get removed from the production set and block the deployment. -## Sync Texts From Production +## **DEPRECATED** Sync Texts From Production + +` As of 02-04-2024, the Coronadashboard has been brought offline, so this chapter is no longer relevant.` Because in the development dataset we typically inject a lot of placeholder texts, running the app locally doesn't always give a good impression of what it diff --git a/docs/page-parts.md b/docs/page-parts.md index e2f7b4c2ed..32e7809b37 100644 --- a/docs/page-parts.md +++ b/docs/page-parts.md @@ -1,8 +1,8 @@ # Page Parts -All pages found on routes `landelijk/[page]` or `gemeente/[code]/[page]` can contain -sections for FAQs, data explanations, and articles. These are referred to as page parts -(or `Pagina onderdelen` in Sanity Studio). A collection of page parts refers to a +All pages found on routes `landelijk/[page]` or `gemeente/[code]/[page]` can contain +sections for FAQs, data explanations, and articles. These are referred to as page parts +(or `Pagina onderdelen` in Sanity Studio). A collection of page parts refers to a `Page composition`. This document outlines how page parts work. ## Data model @@ -15,21 +15,22 @@ the title is **only used to display a human readable name in the Sanity Studio** For any page part, you must first configure the fields found within the `Page configuration (Pagine configuratie)` fieldset. This fieldset consists of: -* Title (`Menu titel`) - Only used to display a human readable name in the Sanity Studio. -* Page ID (`Pagina ID`) - This is a reference to a `pageIdentifier`. -* Page data type (`Pagina data soort`) - This is a unique identfier for a page part. -You can read more about this field in the **Data kind** section below. + +- Title (`Menu titel`) - Only used to display a human readable name in the Sanity Studio. +- Page ID (`Pagina ID`) - This is a reference to a `pageIdentifier`. +- Page data type (`Pagina data soort`) - This is a unique identfier for a page part. + You can read more about this field in the **Data kind** section below. At the moment, we support the following page parts: ### Articles -Also referred to as `Pagina Artikelen`, this page part allows you to add a list of articles to a page. -There is an interface to select a list of articles as well as an interface to add a title for the +Also referred to as `Pagina Artikelen`, this page part allows you to add a list of articles to a page. +There is an interface to select a list of articles as well as an interface to add a title for the articles section on a given page. -The document also has `minNumber` and `maxNumber` fields that indicate a minimum and maximum -number of references. These fields are only visible to administrators, so normal users will only +The document also has `minNumber` and `maxNumber` fields that indicate a minimum and maximum +number of references. These fields are only visible to administrators, so normal users will only be able to edit the article list and the section title. ### Data explained @@ -43,7 +44,7 @@ has an interface for selecting a data explanation item to link to. Also referred to as `Pagina FAQ's`, this page part allows for the addition of FAQ items to a given page. Similar to the data explained page part, configuring FAQs for a page will create a button at the top of -the page which links to the FAQs at the bottom of the same page. +the page which links to the FAQs at the bottom of the same page. The document consists of fields allowing for the configuration of the button's title and subtitle. Similar to page articles, there is a field to add a section title for the FAQ section of a page. Finally, @@ -57,8 +58,8 @@ only be able to edit the links list. ### Highlighted items -A list of highlighted items, currently only used on the Actueel pages. The document also -has `minNumber` and `maxNumber` fields that indicate a minimum and maximum number of items. +A list of highlighted items, currently only used on the Actueel pages. The document also +has `minNumber` and `maxNumber` fields that indicate a minimum and maximum number of items. These fields are only visible to administrators, so normal users will only be able to edit the item list. ## Data kind @@ -69,8 +70,8 @@ page. The page data kind is used in the code to query the content for a particul For example: -This functionality can be use so multiple lists of articles can be added to a page, for example. -One list can be called 'mainPageArticles', another 'specialPageArticles', this name is then +This functionality can be use so multiple lists of articles can be added to a page, for example. +One list can be called 'mainPageArticles', another 'specialPageArticles', this name is then used to identify each list after it has been received from a Sanity query. ## Querying page parts @@ -82,9 +83,7 @@ there are dedicated functions to retrieve any kind of page part. For example: ```ts -const { content } = await createGetContent>( - () => getPagePartsQuery('sewer_page') -)(context); +const { content } = await createGetContent>(() => getPagePartsQuery('sewer_page'))(context); return { content: { @@ -101,9 +100,10 @@ return { The workflow for adding a new page with page parts is fairly simple: [Page part] - Refers to any of the available page parts + 1. Create a new page identifier document (in Sanity, Pagina onderdelen -> Page Identifier) 2. Create a new page part -> (in Sanity, Pagina onderdelen -> [Page part]) -4. Configure the page part by filling in the fields -5. Query the data in the application's page and off you go. +3. Configure the page part by filling in the fields +4. Query the data in the application's page and off you go. [Back to index](index.md) diff --git a/docs/release-procedure.md b/docs/release-procedure.md index 9333569e07..db3991cc8f 100644 --- a/docs/release-procedure.md +++ b/docs/release-procedure.md @@ -1,4 +1,6 @@ -# Release Procedure +# **DEPRECATED** Release Procedure + +` As of 02-04-2024, the Coronadashboard has been brought offline, so this chapter is no longer relevant.` ## Sprint Release diff --git a/docs/styled-system.md b/docs/styled-system.md index b4bc1d731a..1643ace40c 100644 --- a/docs/styled-system.md +++ b/docs/styled-system.md @@ -9,7 +9,7 @@ The theme that holds all of the styling constants is located at **app/src/style/ all styling information, so fonts, font sizes, font weights, colors, etc. Inline styles that set their own property values that are not described in the theme are highly discouraged. The only kinds of exceptions that this rule might be very localized padding and margin settings, for example, -but te rule of thumb is that theme values need to be used whenever possible. +but the rule of thumb is that theme values need to be used whenever possible. ## Typography diff --git a/docs/timeline-events.md b/docs/timeline-events.md index 33ba8dfae5..554a3a7534 100644 --- a/docs/timeline-events.md +++ b/docs/timeline-events.md @@ -1,4 +1,4 @@ -# Timelines && Timeline Events +# Timelines & Timeline Events All time-series charts can optionally render events on a timeline to illustrate and describe certain parts of the data. diff --git a/packages/app/README.md b/packages/app/README.md index 40a101fedb..6176ee91fe 100644 --- a/packages/app/README.md +++ b/packages/app/README.md @@ -1,4 +1,6 @@ -# NL Coronavirus Dashboard - App +# ARCHIVED NL Coronavirus Dashboard - App + +` As of 02-04-2024, the Coronadashboard has been brought offline, so this file is no longer relevant.` The main application that contains the front-end part of the dashboard. This React application uses Next.js as its framework. @@ -8,7 +10,7 @@ React application uses Next.js as its framework. First run `yarn install` or simply `yarn` at the root of the repository if you haven't already. This installs all the dependencies for all of the packages. -Make sure you have an `.env.local` file in `packages/app` with correct environment variables. To +For developers only! Make sure you have an `.env.local` file in `packages/app` with correct environment variables. To get started, you can copy `.env.local.example`: ```sh @@ -17,20 +19,25 @@ cp packages/app/.env.local.example packages/app/.env.local Then from the repository root you can run: -1. `yarn download` - Downloads latest data +1. ~~`yarn download` - Downloads latest data~~ The latest production protos have been added to the repository. The user is not required to download them. 2. `yarn bootstrap` - Downloads / builds all other requirements 3. `yarn dev` - Starts the development server -These steps are described in more detail below. +By default, the archived application is configured to run with the latest production data and lokalize-keys. The steps described above are outlined in more detail below. ### JSON Data -Run `yarn download` to download & install the JSON data files from production in -`packages/app/public/json` +~~Run `yarn download` to download & install the JSON data files from production in `packages/app/public/json`~~ The calculations for the data can be found in [nl-covid19-data-backend-processing](https://github.com/minvws/nl-covid19-data-backend-processing). +JSON data files represent a collection of archived and non-archived "protos" files that contain the key-value pairs for the entire website. The protos are split into 3 categories and can be found in the `packages/app/public/json` folder: + +1. NL & Archived NL: A collection of data that is used by `/landelijk/*` +2. GM_COLLECTION & Archived GM_COLLECTION: A collection of data that is only used by the `choropleths` +3. GM & Archived GM: A collection of data that is used by municipality pages. The GM code is directly linked between the `GMXXX.json` file and `gemeente/GMXXX/*` page. + ### CMS Dataset By default, the site builds using the development dataset. If you would like the @@ -81,6 +88,5 @@ There are several scripts available via `yarn [scriptName]`. - `dev` Runs the app in the development mode. Open [http://localhost:3000](http://localhost:3000) to view it in the browser. - `build` Builds the app for production to the `out` folder. -- `download` This downloads the latest data files from the production server and - places the data in the `public/json` folder. +- ~~`download` This downloads the latest data files from the production server and places the data in the `public/json` folder.~~ - `test` Runs the unit tests. diff --git a/packages/cms/README.md b/packages/cms/README.md index 39bd7b78bb..1fd779e5e6 100644 --- a/packages/cms/README.md +++ b/packages/cms/README.md @@ -5,7 +5,7 @@ developers that have access to the CMS. ## Usage -Run `yarn dev` to serve the CMS. This will run the `sanity dev` command. The CMS can be run on an alternate port using `--port XXXX` in which `XXXX` is the port number. +Run `yarn dev` to serve the CMS. This will run the `sanity dev` command. The CMS can be run on an alternate port using `--port XXXX` in which `XXXX` is the port number. The command cannot be run in parallel with `yarn dev`from the app root folder. Previewing production builds of the CMS are done using `yarn build` and `yarn start` from this directory respectively.