✏️feat: revise README.md (#205)

* ✏️ refak: revise README.md - Add og image - Add Issues and Pull Requests - Add Communcation - Add Development - Add License - Revise existing content * ✏️ refak: revise README.md - Remove refak - Fix link - Add special thanks * ✏️ refak: revise README.md - Fix header typo - Fix license link - Revise wordings in i18n - Add missing emoji - Add link to Kintohub * ✏️ refak: revise README.md - Fix graphql link - Remove target="_blank" * ✏️ refak: revise README.md - Add nvm-related info - Add Vounteers content - Make Examples bold * ✏️ refak: revise README.md - Add Data
vote4hk · Apr 4, 2020 · 174f007 · 174f007
1 parent 20642c8
commit 174f007
Showing 1 changed file with 158 additions and 15 deletions.
diff --git a/README.md b/README.md
@@ -1,38 +1,171 @@
+<div align="center">
 <h1>
-  Fight for freedom, Stand from MO HONG
+  Fight for freedom, Stand from Wuhan
 </h1>
+This is the repository for <a href="https://wars.vote4.hk">wars.vote4.hk</a>
+<br/>
+<br/>
+<a href="https://wars.vote4.hk/">
+  <img height="480" src="https://github.com/nandiheath/warsinhk/blob/master/static/images/og_share_en.png?raw=true">
+</a>
+</div>
 
 ## 🚀 Quick start
 
-### 1. Start developing
+### Set up your environment
 
-Navigate into your new site’s directory and start it up.
+Navigate to the project directory and run the below command to install all the dependencies of project
 
 ```bash
 yarn
 ```
 
-### 2. Open the source code and start editing
+### Start your local development
 
 ```bash
 gatsby develop
 ```
 
 Your site is now running at `http://localhost:8000`!
 
-_Note: You'll also see a second link: _`http://localhost:8000/___graphql`_. This is a tool you can use to experiment with querying your data. Learn more about using this tool in the [Gatsby tutorial](https://www.gatsbyjs.org/tutorial/part-five/#introducing-graphiql)._
+**Note:**
 
-## 🌟 Contributing
+- You'll also see a second link: `http://localhost:8000/___graphql`. This is a tool you can use to experiment with querying your data. Learn more about using this tool in the [Gatsby tutorial](https://www.gatsbyjs.org/tutorial/part-five/#introducing-graphiql).
+- Gatsby requires Node.js 10.13.0 or higher. If your version is below the required one, try to upgrade it or following the below steps to switch to the desired version using [`nvm`](https://github.com/nvm-sh/nvm):
+  Run the following command to use the version from inside the `.nvmrc` file
+  ```bash
+  nvm use
+  ```
+  If the specified version is not found, please run the following command to install
+  ```bash
+  nvm install
+  ```
 
-### 1. Fork this repo
+## 🌟 How to contribute
 
-In this project we use `dev` branch for all developments. All PR will be reviewed and then merge into `dev`.
+All contributions are welcome.
 
-### 2. Checkout the latest code
+### For Volunteers:
 
-Please setup the master repo `github.com/nandiheath/warsinhk` as `upstream` and `git fetch upstream -p` everytime before commit. And remember to rebase your branches onto latest `upstream:dev`
+- Apply through [Google Form](https://docs.google.com/forms/d/e/1FAIpQLSfO8BPKrJVIN21Di2-xOHP_iSAcDv_kxNa6EfanshsSwo6bQw/viewform).
+- Submit Github Issues for reporting bugs. (See below `Issues` section for more).
 
-### 3. Run the code on your local to ensure it is working
+### For Developers:
+
+- See below `Development` section for more.
+
+### Issues
+
+- Please follow our issue template when creating an issue. We only accept `bug report` and `feature request`. Before creating an issue, make sure there is no similar issues.
+- If you plan to work on an issue, please leave a comment to inform us and we will assign it to you. We recommend beginners to pick up issues with [good first issue](https://github.com/nandiheath/warsinhk/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) tag.
+
+### Pull Requests
+
+- Please follow our pull request template when creating a pull request. Make sure your pull request fulfils our requirement.
+- Please create a new branch (for each PR) based on the latest `dev` or the feature branch and name it either `feat/<meaningful_name>` or `fix/<meaningful_name>`.
+- Please follow our naming convention `🌟[feat/fix]: [summary]` (pick your favourite emoji 😉) for pull request title.
+
+### Communication
+
+- We make communication in a Telegram Group. Feel free to join us by clicking [here](https://t.me/joinchat/BwXunhP9xMWBmopAFrvD8A).
+
+## 💻 Development
+
+### Branches
+
+| Purpose     | Branch  | URL                        | Remarks                                                                                       |
+| ----------- | ------- | -------------------------- | --------------------------------------------------------------------------------------------- |
+| Development | dev     | https://wars-dev.vote4.hk/ | Default development branch. All pull requests will be reviewed and then merged to this branch |
+| Production  | master  | https://wars.vote4.hk/     | Only pull requests created by administrators are allowed                                      |
+| Hotfix      | fix/\*  | None                       | Fixes created by the administrators                                                           |
+| Feature     | feat/\* | None                       | Features branch before merging to Development branch                                          |
+
+### Checkout the latest code
+
+Please setup `dev` repo `github.com/nandiheath/warsinhk` as `upstream` and `git fetch upstream -p` everytime before making commits. And remember to rebase your branches onto latest `upstream:dev`.
+
+### Internationalization (i18n)
+
+We are using [react-i18next](https://react.i18next.com/) to assert that the internationalized content can be loaded or that it gets rendered when the language changes.
+
+The translation json files for `en` and `zh` are located at `src/locales/en/translation.json` and `src/locales/zh/translation.json` respectively. By default, `zh` is used. If you have changes to the wordings, please make sure they are added or updated in both json files.
+
+**Examples:**
+
+src/locales/en/translation.json
+
+```json
+{
+  "world.page_title": "Global Cases"
+}
+```
+
+src/locales/zh/translation.json
+
+```json
+{
+  "world.page_title": "全球疫情追蹤"
+}
+```
+
+Use `useTranslation()` for functional components:
+
+```js
+// 1. import useTranslation from react-i18next
+import { useTranslation } from "react-i18next"
+// 2. define t from useTranslation()
+const { t } = useTranslation()
+// 3. use the t function with the key as the parameter
+const title = t("world.page_title")
+```
+
+Use `withLanguage()` to translate the target field within an object
+
+```js
+// 1. import withLanguage from custom utils
+import { withLanguage } from "@/utils/i18n"
+// 2. define i18n from useTranslation()
+const { i18n } = useTranslation()
+// 3. pass i18n, the target object, and the target field name to withLanguage
+// if the locale is en, the link would be ``node.address_en``
+// if the locale is zh, the link would be ``node.address_zh``
+const address = withLanguage(i18n, node, "address")
+```
+
+Use `getLocalizedPath(i18n, path)` to get the localized path
+
+```js
+// 1. import getLocalizedPath from custom utils
+import { getLocalizedPath } from "@/utils/i18n"
+// 2. define i18n from useTranslation()
+const { i18n } = useTranslation()
+// 3. pass i18n and the path to getLocalizedPath
+// if the locale is en, the link would be ``/en/world``
+// if the locale is zh, the link would be ``/zh/world``
+<Link
+  href={getLocalizedPath(i18n, "/world")}
+>
+  ...
+</Link>
+```
+
+For interpolation, surround the dynamic value by curly brackets in `translation.json`
+
+```json
+{
+  "world.border_shutdown_last_update": "Last update: {{date}}"
+}
+```
+
+and pass an object with the key defined in curly brackets and the dynamic value in the second parameter
+
+```js
+{
+  t("world.border_shutdown_last_update", { date: last_update })
+}
+```
+
+### Analyse code for potential errors
 
 Run eslint to ensure it fits linting
 
@@ -41,13 +174,23 @@ yarn lint
 yarn lint:fix
 ```
 
-Try build to see if any errors
+Try to build to see if there are any errors.
 
 ```bash
 yarn build
 ```
 
-### 4. Create branch for every PR
+## 📍 Data
+
+The data is updated automatically every 5 minutes. The information are all open for use. If you wish to cite anything from this site, please credit us as `wars.vote4.hk - COVID-19 in HK`.
+
+- [High-risk Areas](https://docs.google.com/spreadsheets/d/e/2PACX-1vT6aoKk3iHmotqb5_iHggKc_3uAA901xVzwsllmNoOpGgRZ8VAA3TSxK6XreKzg_AUQXIkVX5rqb0Mo/pub?gid=0&range=A2:ZZ)
+- [Confirmed Cases](https://docs.google.com/spreadsheets/d/e/2PACX-1vSr2xYotDgnAq6bqm5Nkjq9voHBKzKNWH2zvTRx5LU0jnpccWykvEF8iB_0g7Tzo2pwzkTuM3ETlr_h/pub?gid=0&range=A2:ZZ)
+
+## 📄 License
+
+This software is released under [the MIT License](https://github.com/nandiheath/warsinhk/blob/master/LICENSE).
+
+## 💡 Special Thanks
 
-Create `fix/` `feat/` branch and submit PR to `dev`.
-The PR title please follow our naming convetion `🌟[feat/fix]: [summary]` (pick your favourite emoji 😉)
+Thanks to <a href="https://www.kintohub.com/"><img src="https://wars.vote4.hk/images/kintohub_icon.svg" style="width:30px; height:15px;">Kintohub</a> for the sponsorship on our server cost.