ehharding/angular-laws

An Angular Application To Discover Laws

Angular Laws

An Angular Website Built With Angular Material

Executive Summary

A modern law viewing website built with Angular and Angular Material. This project is a work in progress but its larger goal is to provide a modern law viewing experience while also serving as an educational tool for understanding law and legal concepts.

Developer Environment Recommended Setup

To build from source and to contribute to the project, you will need to do a couple of things to get going. It is my goal that every developer have the same development environment configuration. So, this section will go over both the tools required to work on the project and the recommended general setup.

IDE And Project Setup

First, you'll need Git and Node.js (which comes with npm) installed on your computer. You must download an Active LTS or Maintenance LTS release of Node.js. You can find out which versions these are by visiting the Node.js release site. After you have installed Node.js, enter the following from your command line of choice:

# Go To The Top-Level Directory On Your Machine
cd /

# Create Working Directory And Go Into It
mkdir Scratch && cd Scratch

# Clone The Repository
git clone https://github.com/ehharding/Angular-Laws.git

Then, you should download JetBrains' Webstorm IDE for your platform (Windows, macOS, or Linux). WebStorm includes a free 30-day trial, but you will most likely want to purchase a license to use all of its features.

You will need to go through a setup routine for the Material Theme UI plugin. Personally, I use the Night Owl theme.

Finally, while Chrome, Edge, Firefox, Opera, and Safari are supported as browsers, I would highly recommend Firefox as your core development browser. You will need it to properly run the project unit tests.

Installing Project Dependencies

You must now install the necessary dependencies for the project via npm. From WebStorm's Terminal command line:

# Go To Repository Directory If Terminal Does Not Automatically Put You Here
cd /Scratch/Angular-Laws

# Install Dependencies Via npm
npm install

Running The Project Locally

With dependencies installed, you should now be ready to actually run the project. Either double click the start npm script or run the following npm command:

npm run start

Angular should have compiled the project and served it to http://localhost:4200/. Point your browser here to see the site. You will not be able to push to the GitHub repository without first being added as a project contributor.

Running The Project Unit Tests

You can run unit tests for the project via the test and test:watch npm scripts or run the following npm commands:

# Run Unit Tests Inside Firefox And Watch The Results
npm run test:watch

# Run Unit Tests Inside A Headless Firefox (You Can Still See The Results In The Terminal)
npm run test

Linting The Project

To help with code maintainability and quality, this project utilizes ESLint along with the @typescript-eslint and eslint-plugin-tsdoc plugins. To run the linter on the project, you can use the lint and lint:report npm scripts or run the following npm commands:

# Run ESLint On The Project
npm run lint

# Run ESLint On The Project And Output An HTML Report Of The Results
npm run lint:report

Getting Your Changes Integrated Into The Project

For now, all contributors are simply pushing their changes to the main GitHub branch. Of course, in the future, this could conceivably be more of a pull-commits-into-main situation.

To be allowed to push to the main branch, you must first have the "Direct Access" permission in the Angular Laws repository. After this is given, you will then need to configure your local Git client to use a GPG key to communicate securely with the GitHub server. The first step in this process (after being given access) is to generate a 4,096 bit RSA key. To do this, from a CLI:

# Tells Git What The GPG Program To Use Is And To Always Sign Commits
git config --global gpg.program gpg
git config --global commit.gpgsign true

# Generate A Key (Stepper Process - USE YOUR GITHUB ACCOUNT EMAIL/USERNAME, Select 4,096 bit RSA, No Expiration)
gpg --full-generate-key

Now, Git should have created a public/private key on your system. Keep the private key, logically, private and secure. The public key will be used to authenticate with GitHub. To see your newly generated key, run the following:

# List The Long Form Of The GPG Keys For Which You Have Both A Public And Private Key
gpg --list-secret-keys --keyid-format=long

If successful, something like the following will be shown:

/Users/hubot/.gnupg/secring.gpg
------------------------------------
sec 4096R/3AA5C34371567BD2 2016-03-10 [expires: 2017-03-10]
uid Hubot
ssb 4096R/42B317FD4BA89E7A 2016-03-10

Take the GPG key ID (the "3AA5C34371567BD2" part shown in the above example) and feed it to the following command to see your public key block, which will be associated with your GitHub user account:

# Substitute Your GPG Key ID As The Last Argument
gpg --armor --export xxxxxxxxxxxxxxxx

The GitHub Angular Laws repository will then need to be modified to include a contributor with the public GPG key block output above. Finally, configure your Git client to use your newly generated public key:

# Substitute Your GPG Key ID As The Last Argument
git config --global user.signingkey xxxxxxxxxxxxxxxx

After doing this, when you commit, Git should prompt you for your password that encrypts/decrypts your public/private GPG key pair. If successful, the repository shows the commit as a verified commit.

Credits

This software uses the following open source packages:

• Angular — Google's modern web development framework
• Angular Material — Google's Material Design components for Angular
• Bootstrap — A popular front-end open source CSS toolkit
• RxJS — A library for composing asynchronous and event-based programs using observable sequences
• TypeScript — Microsoft's open source programming language that extends JavaScript
• ESLint — A modern code linter for JavaScript/TypeScript
• ESLint Plugin TypeScript — An ESLint TypeScript plugin that extends ESLint's tools for TypeScript-targeted code style enforcement
• ESLint Plugin TSDoc — An ESLint TSDoc plugin that extends ESLint's tools for TypeScript-targeted documentation style enforcement
• Jasmine — A behavior-driven JavaScript unit testing framework
• Karma — A JavaScript unit test runner
• Node.js — A JavaScript runtime built on Chrome's V8 JavaScript engine
• npm — The Node Package Manager (npm)

License

Apache 2.0