platypusio/cloud-sdk-nodejs12

🦦 The Platypus - Frontend

📑 Table of Contents

• 🏎 Quick Start
  • yarn or yarn install
  • yarn dev
  • yarn build & yarn start 3000
  • yarn test
• 🚀 Deployment
• 🎰 Versioning & Releases
  • Releasing with release-it
  • yarn release [major|minor|patch]
  • yarn release:ci [major|minor|patch]
  • Semantic Versioning
  • Creating a docker image
• 📃 Documentation
  • Marking as todo:
  • Committing
    • Rule of thumb:
    • Scope tags
    • Short description
• 🅰/🅱 Tests
  • https://platypusv2.appspot.com&testKey={key}&testValues={value}
  • 🧾 Query
    • Example:
  • 🎣 Hook
    • Example:
• 🎿 Performance Monitoring
• 🕷 Bug Reporting
  • Sentry
  • QA
• 🩹 Patches
  • Creating patches
• 💅 Sass Documentation
  • Z-Index Rules
• GQL
  • Creating GQL query/mutations on Hasura
  • Hasura Headers
  • Using generate.sh to automatically generate GraphQL schema
• 🔠 Translations
  • Creating Translations through Github Desktop.
    • ⚙ Setup/Preparing for translating
    • ✒ Creating Translations
• 🌿 Branching
• Components
  • Autosuggest / Search
• SVG's
  • Dependencies
  • Adding SVG's
• 🧪 Testing / Cypress

**Table of content created using VSCode extension: https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one

🏎 Quick Start

Run the following command to get your project installed, and up and running.

sh
git clone git@github.com:theplatypusio/frontend.git
cd frontend
yarn install

yarn or yarn install

Install the modules defined in the package.json, with version from yarn.lock

yarn dev

Runs the app in development mode.
Open http://localhost:3000 to view it in the browser.

The page will automatically reload if you make changes to the code.
You will see the build errors and lint warnings in the console.

yarn build & yarn start 3000

Builds the app to the .next folder.
Once you've runned yarn build, you can spin up the Next.js node server by running yarn start. You'll need to suffix the start command with the Port (3000), due to our Hosting.

sh
# Build the project and start the node server
yarn build && yarn start 3000

yarn test

Runs the test watcher in an interactive mode.
By default, runs tests related to files changed since the last commit.

[Read more about testing.] https://reactjs.org/docs/testing.html

🚀 Deployment

We're deploying through https://app.circleci.com/pipelines/github/theplatypusio/frontend

• test branch automatically deploys to [***]
• prod branch automatically deploys to [] & []

🎰 Versioning & Releases

Releasing with release-it

We're using https://github.com/release-it/release-it to update our version number correctly, and create Github Tag & Releases.

yarn release [major|minor|patch]

yarn release starts an Interactive CI which pro***s you with questions, that helps you make a decision on which kind of release it is.

You can bump a specific version, by appending either major, minor or patch. Like so yarn release patch.

yarn release:ci [major|minor|patch]

yarn release:ci starts a CI which makes a specific release, but without pro***ing questions. Instead it picks the default settings from the package.json file

Read more about release-it here: https://github.com/theplatypusio/frontend/edit/test/README.md

Semantic Versioning

We're following the traditional Semver rules.

Given a version number MAJOR.MINOR.PATCH, increment the:

• MAJOR version when you make incompatible API changes,
• MINOR version when you add functionality in a backwards compatible manner, and
• PATCH version when you make backwards compatible bug fixes.

Read more about semver here: https://semver.org/

Creating a docker image

The creation of the docker image used by CircleCI to build the application can be found https://github.com/theplatypusio/frontend/blob/test/Dockerfile.

The Dockerfile gets build automatically by DockerHub, the docker image build step is triggered by a tag that matches the following regex expression: /^v([0-9.]+)-docker$/. The image will be tagged with the numerical part of the git tag(ex: git tag : v1.2.3-docker, docker image tag: 1.2.3). The build process takes a bit of time, to check when it's done go https://hub.docker.com/repository/docker/platypusio/cloud-sdk-nodejs12. After pushing go and delete the README from the repository, so we don't expose sensitive data, as the docker image is public (The README is automatically updated by DockerHub).

After creating a new image remember to change the image version in the CircleCI file https://github.com/theplatypusio/frontend/blob/bf432f824dc8fe618a20f0a449b3910bb33d0599/.circleci/config.yml#L14.

📃 Documentation

Marking as todo:

If you're working on a task, and a issue occur, which is not solvable within scope, then create a todo: comment.

The comment should include:

• A description of the issue/problem
• Ideal way to solve it
• @author (the responsible person)

Committing

When committting task, we're using the tool https://github.com/commitizen/cz-cli.

Rule of thumb:

• We prefer many commits, over big commits.
• We prefer isolated/specific commits, over messy/all-over-the-place commits.

Scope tags

• {component-name}
• component
• utils

Short description

A description of what's been done in the commit.

🅰/🅱 Tests

https://platypusv2.appspot.com&testKey={key}&testValues={value}

🧾 Query

You can create A/B Tests by creating a unique key: testKey and provide it with values: testValues.

Example:

http
https://platypusv2.appspot.com/print_creation/intro?link_token=eyJ0eXBlIjoiYXBwbGljYW50IiwiY29tcGFueV9pZCI6MSwicG9zdGluZ19pZCI6MX0=&testKey=point_quantity&testValues=25

This is an A/B Test for Point Quantity, which is testing with the value of 25 points.

🎣 Hook

For each feature, we're creating a hook (example: usePrintCreationABTest), which is invoked which is invoked with the specific key, and optionally which store it relates to.

Example:

tsx
const { isCompleted, setTestDone } = usePrintCreationABTest({
  key: 'point_quantity', // < The Unique Key as identifier
  storeKey: 'printCreation', // < The Redux Store
});

🎿 Performance Monitoring

We're tracking the speed through Speedtracker.

See the benchmarks here: https://theplatypusio.github.io/speedtracker

🕷 Bug Reporting

Sentry

• We're using Sentry to track our JS errors in the frontend. Contact a colleque to get an invite

https://sentry.io/auth/login/theplatypus/

QA

To report bugs/corrections/suggestions we use Marker.io.

1. Install the Marker.io browser extension, and log in at the extension.
2. When you want to report a bug, use the extension to mark the area that you want to highlight, and mark what the issue is.

🩹 Patches

Creating patches

We're using https://github.com/ds300/patch-package#readme to patch modules.

To patch a module do the following.

sh
# Navigate to the node_modules folder, and then fix the issue.
vim node_modules/package_name/flawful_file.js

sh
# Run the patch function
npx patch-package {package_name}

sh
# Commit the patched file inside of the `/patches` folder.
git add patches/*
yarn release:ci patch

💅 Sass Documentation

Z-Index Rules

GQL

Creating GQL query/mutations on Hasura

• You need access to hasura and then go to Hasura Web App
• After that build your query/mutation by selecting whats needed, test it by running it, and then copy the query/mutation that has been built for you.
• Paste the copied query/mutations into src/gql/* (any file based on where it supposed to be.)
• Get a valid token by logging into the Platypus web app (IMPORTANT!: as Super User) and pasting the following command in the console copy(__NEXT_REDUX_STORE__.getState().auth.token) (The token will be copied to clipboard)
• Run the generator using the token as the following AUTH_TOKEN={token} yarn generate --watch PS: if you got an error regarding fields not being found check that you have the right access first (a super user is the perfect scenario) other than that issues in the query/mutation need to be fixed for it to run right.
• After that your query/mutation hook should be found in the src/__generated__/graphql.ts and ready to be used and already typed.

Hasura Headers

Using generate.sh to automatically generate GraphQL schema

• You need to have jq installed on your system. It is used to parse JSON returned from the login request.

sh
# Mac
brew install jq

# Linux / Windows (WSL):
apt-get install jq

Make sure that you an .env file with these values:

• AUTH_API_BASE_URL = The authentication service URL
• ADMIN_MAIL = Email of the user
• ADMIN_PASS = Pass of the user

Once you have all this, you can simply run:

sh
./generate.sh

If you run into permissions issues, you can do this for Mac:

sh
chmod u+x ./generate.sh

This will give exec permission for the current user.

🔠 Translations

Creating Translations through Github Desktop.

⚙ Setup/Preparing for translating

1. Download https://desktop.github.com/ and https://github.com/gilmarsquinelato/i18n-manager/releases/latest and install them.
2. Open Github Desktop and login. (The login requires 2FA, which only Mads Thines (@mthines) has)

Ask a developer for the password

username: PlatyMem
password: ****

3. Through Github Desktop, navigate to the Frontend repository, and clone it down.

See video on how to setup: [***]

✒ Creating Translations

1. Open Github Desktop and make sure you're on the test branch. Then create a new branch called translations. (If there already is a branch called translations, delete it and recreate it using the Github Desktop).
2. Now open the directory public/static/locales project in i18n Manager
3. Do the translations using the i18n Manager.
4. Once done, go back to the Github Desktop, make sure you're on the newly create translations branch, and commit the changes using the bottom left interface (Please add a commit message which gives a context of what's been translated).
5. Push the commit, and then make a Pull Request towards the test branch, and assign a reviewer (right side of Github Pull Request view)
6. And you're done - Now just wait for a developer to approve the changes, and they will deploy them.

See video on how to create translations: [***]

🌿 Branching

features/{feature-name}

Branches for features that can include tasks or sub tasks under that it taken from test (or development later)

task/task-name

Branches for tasks which falls under a feature and is branched out from a feature branch

bugfix/bug-name

Branches for features and releases bug fixes that is branched out from a feature or a release branch

hotfix/fix-name

Branches for test hot fixes that branched out from test branch

release/release-tag

(this is not used now because we are using test directly) it's for releases branch for test needs before merging to test

Strategy

1. Create your feature branch out from prod
2. When the feature is done you merge feature into test. (never pull the test branch into your feature branch)
3. Test the feature on test
4. If everythings working as expected, write a "How to test" on the Asana task and send the task to QA in the #testing channel in Slack
5. If there is bug, fix it on the feature branch and create a new PR towards test.
6. (Repeat step 3-5 until everythings working as expected).
7. Once the feature approved by QA, merge the feature branch into prod
8. Once the feature is merged into prod, test the feature on demo. (Not prod)

!Branching Strategy

SVG's

Dependencies

• https://github.com/svg/svgo
• https://github.com/guylando/svgo-addViewBox

Adding SVG's

1. Add the SVG to the project, depending on how it should be used.

• /public/icons/* <- Icons that shouldn't be compiled through Webpack.
• /src/assets/icons/* <- Icons that should be compiled through Webpack and merged into the markup.

2. (If you haven't already, install both SVGO and the addViewBox plugin)

3. Run svgo src/assets/icons/* --enable=addViewBox

4. Add it to the <Icon /> components iconsMap

🧪 Testing / Cypress

To be honst just just check the Tests written already and here is the docs https://docs.cypress.io/

https://docs.cypress.io/guides/guides/continuous-integration.html#Advanced-setup