Mdlinx-smartestdoc NPM

Smartest Doc Prototype

This is a the next iteration of Smartest Doc. The frontend is built on the Next.js framework, which uses React. As you'll see from the code, this started as a throw away prototype which was then converted into what is in production right now.

Setting up a dev environment

Install Node.js (>= v8.0.0)
Install the Yarn package manager
Clone this repository
(N.B. If running Windows, please don't clone the repository into the My Documents path - Node will not be able to find all of the modules needed to run the server if you do.)
Inside the repo, run yarn to install node modules
If running Windows, run npm install -g win-node-env to allow the npm script commands to run normally without modification.
Run yarn dev to start the dev server
Go to localhost:3000 in your browser

Deploying to Production

Deployment is done using AWS Elastic Beanstalk. You will need to install the eb-cli.

After following the instruction to install the eb-cli from the link above, follow these steps to deploy:

To deploy: 1. Make sure the code you want to deploy is committed and at the head of your branch. eb-cli will deploy the head of the current branch you are on. 2. Run eb deploy sd-frontend-prod 3. You will see output of the deploy process in the terminal and see a message indicating when deployment is complete.

Troubleshoot Production

You will need to access the AWS EB console, there are logs and other monitoring available in the console.

Git Workflow - Gitflow

We are using the Gitflow workflow in this project. Gitflow is just an abstract idea of a Git workflow. This means it dictates what kind of branches to set up and how to merge them together. The Gitflow Workflow defines a strict branching model designed around the project release

There is a GitFlow tool chain that is a collection of Git extensions to provide high-level repository operations.

To install on Mac OSX, execute

brew install git-flow

On Windows you will need to download and install git-flow

Develop and Master Branches

Instead of a single master branch, this workflow uses two branches to record the history of the project. The master branch stores the official release history, and what is currently in production, and the develop branch serves as an integration branch for features.

All development happens in feature branches that are based on the latest develop. Once develop has acquired enough features for a release (or a predetermined release date is approaching), you create a release branch off of develop. Creating this branch starts the next release cycle, so no new features can be added after this point—only bug fixes, documentation generation, and other release-oriented tasks should go in this branch. Once it's ready to ship, the release branch gets merged into master. In addition, it should be merged back into develop, which may have progressed since the release was initiated. Using a dedicated branch to prepare releases makes it possible to polish the current release while features for the next release can continued to be developed.

Creating a feature branch

Without the git-flow extensions:

git checkout develop
git pull
git checkout -b feature_branch

When using the git-flow extension:

git flow feature start feature_branch

Continue your work and use Git like you normally would.

Finishing a feature branch

When you’re done with the development work on the feature, the next step is to submit a PR to merge the feature_branch into develop.

Creating a release branch

Making release branches is another straightforward branching operation. Like feature branches, release branches are based on the develop branch. A new release branch can be created using the following methods.

Without the git-flow extensions:

git checkout develop
git pull
git checkout -b release/0.1.0

When using the git-flow extensions:

$ git flow release start 0.1.0
Switched to a new branch 'release/0.1.0'

Once the release branch is created, deploy it for QA to test.

Finishing a release branch

When all bugs have been resolved and the release is ready to deploy to production. Sumbit at PR to merge release into master.

Once release is merged into master. Deploy to production and merge master into develop

Hotfix Branches

Maintenance or “hotfix” branches are used to quickly patch production releases. Hotfix branches are a lot like release branches and feature branches except they're based on master instead of develop.

Without the git-flow extensions:

git checkout master
git pull
git checkout -b hotfix_branch

When using the git-flow extensions:

$ git flow hotfix start hotfix_branch

Deploying to Elastic Beanstalk

Use the eb-cli

Required tooling

While familiarity with a given IDE/editor is useful, there are some pretty huge advantages to using something like VSCode on a project like this. Especially relevant here are format on save and TypeScript integration. Alternative options include Atom, WebStorm, and if you value performance over literally everything else, Sublime.

TypeScript

What

TypeScript is a compile-to-Js superset of Javascript. The syntax should be familiar to people who know Js.

Why

It's standard practice to use some sort of transpilation for Javascript these days. The core language has been changing very quickly over the last few years, so being able to use these new and shiny features without worrying about browser compatibility is a big advantage. It also enables you to use React's JSX syntax which is significantly more friendly than pure Js, i.e.

<form>
  <input value="string here" />
</form>

is much easier to read and write than

React.createElement(
  "form",
  null,
  React.createElement("input", { value: "string here" })
);

Because we have this transpile step by default, using either FlowType or TypeScript to add static typing to Javscript doesn't really have a downside. There is a bit of a learning curve, but it's worth it. In this case, we're opting to go with TypeScript because it's a much easier to work with out of the box and has a much larger following than FlowType.

Using TypeScript helps you write safer code in a couple of ways.

With an editor plugin (or VSCode's built in support), you can hover over variables to inspect them, which makes it significantly quicker to grok a section of code without having to skim 5 different files. The bad old days of not being sure how to use that method you're passed correctly or which attributes are available on a huge mutable object are thankfully over.
In a similar wrist-slapping fashion to ESLint, TypeScript will warn you if you try to do something it knows won't work. Sometimes it's something obvious like 3 * "3", but sometimes it's more subtle. In either case, it'll save you time now and when you test later.

Prettier

What

Code formatter for Js/TS. Strongly recommend installing a plugin and enabling format on save in your editor of choice.

Why

In source control, we want:

To minimise the number of changes in each PR to make code reviews as easy as possible.
Code uniformity so when we're trying to grok something, we're not distracted by code style differences.

It's tempting when you find badly formatted code to fix it, or to replace someone else's code style choices, but that clutters the commit unecessarily. Using ESLint, you'll get a slapped wrist for every little mistake you make which can become very time consuming. Prettier on the other hand rewrites your changes with its own opinionated formatting. Your file is identical to my file and it took zero effort.

Making formating this easy also means that you can write really sloppy code and let Prettier tidy it up. Re-indenting lines, adding missing semicolons, breaking a long line into multiple lines — when you don't have to think about any of that, you'd be surprised how much of a difference it makes.