Table of Contents

• About this Project
  • Built With
  • Environment Dependencies
  • Recommended Browser Extensions
• Getting Started
  • Zero-Installation Development
  • Docker Installation
• Contributing
  • Agile Development
  • Testing
  • Gitflow
  • Commitizen
  • Diagramming
• Workflow Automation
  • CI
  • CD
  • Dependency Management
  • Static Code Analysis
• License

About this Project

This repository is an inclusive extension of piotrwitek's collection of utility types, complementing TypeScript built-in mapped types and aliases (think "lodash" for static types). See utility-types for more information.

Built with

• Typescript
• Mocha

Environment Dependencies

• NodeJS (14 with npm ^6.14.8)

Recommended Browser Extensions

It is recommended that you install the following browser extensions for the best experience interacting with this repository:

1. Gitpod Browser Extension

Getting Started

Zero-Installation Development

It is highly recommended to conduct development of this repository via Gitpod's Theia IDE. Click the following to get started with zero installation requirements:

Gitpod is a one-click online IDE for Cloud-based development. The following video provides a very effective introduction to Gitpod: https://www.youtube.com/watch?v=qLv6-Uop0yc.

Docker Installation

Alternatively, this repo supports VS Code Remote Container Development for Dockerized development inside VSCode.

Step #1: To get started, first make sure to install the followin prerequisites:

1. Visual Studio Code

   • Manual installation: https://code.visualstudio.com/download
   • Windows (via Chocolately):

     choco install vscode

   • Mac or Linux (via Homebrew):

     brew update
     brew tap homebrew/cask-cask
     brew cask search visual-studio-code
     brew cask install visual-studio-code

2. Visual Studio Code Remote Development extension pack, which can be installed into VS Code with this manual installation link.

3. Docker Desktop

   • Manual installation: https://www.docker.com/products/docker-desktop for Widows / Mac
   • Windows (via Chocolately):

     choco install docker-desktop

     and follow
   • Mac or Linux (via Homebrew):

     brew cask install docker

   • Linux (Ubuntu, Debian):

     sudo apt-get update
     sudo apt-get remove docker docker-engine docker.io
     sudo apt install docker.io
     sudo systemctl start docker
     sudo systemctl enable docker

Step #2: Start the Docker daemon if it has already not started automatially after the installation finishes (run the Docker Desktop application). To ensure docker is running, attempt the following commands:

docker version
docker run hello-world

Step #3: Start VS Code and press F1 to run Remote-Containers: Clone Repository in Container Volume.. from the Command Palette.

Step #4: Enter this repository's Git URI: https://github.com/Rad-r-inc/utility-types.git. VS Code will install all required dependencies and set up the environment from the Dockerfile configuration.

Contributing

Agile Development

We are uncovering better ways of developing software by doing it and helping others do it.

Through this work we have come to value:

• Individuals and interactions over processes and tools
• Working software over comprehensive documentation
• Customer collaboration over contract negotiation
• Responding to change over following a plan

That is, while there is value in the items on the right, we value the items on the left more.

Furthermore, we value these principles:

1. Our highest priority is to satisfy the customer through early and continuous delivery of valuable software.
2. Welcome changing requirements, even late in development. Agile processes harness change for the customer's competitive advantage.
3. Deliver working software frequently, from a couple of weeks to a couple of months, with a preference to the shorter timescale.
4. Business people and developers must work together daily throughout the project.
5. Build projects around motivated individuals. Give them the environment and support they need, and trust them to get the job done.
6. The most efficient and effective method of conveying information to and within a development team is face-to-face conversation.
7. Working software is the primary measure of progress.
8. Agile processes promote sustainable development. The sponsors, developers, and users should be able to maintain a constant pace indefinitely.
9. Continuous attention to technical excellence and good design enhances agility.
10. Simplicity--the art of maximizing the amount of work not done--is essential.
11. The best architectures, requirements, and designs emerge from self-organizing teams.
12. At regular intervals, the team reflects on how to become more effective, then tunes and adjusts its behavior accordingly.

Testing

Each contributor to this repository is obligated to provide sufficient test coverage over their contributios. We extend the mocha test framework with the chai assertion library to write more BDD-esque tests.

Test suites are written in typescripts in a .spec.ts file corresponding to the .ts file being tested. For example, the test cases for example.ts should be specified in example.spec.ts. The testing framework will automatically detect all .spec.ts files in the src/ directory.

Gitflow

Version control with git on this repo is in strict adherence to the Gitflow Workflow. Gitflow was architectured by Vincent Driesssen in 2010 and since has been adopted with massive popularity as a very effective development workflow under distributed version control.

This project makes use of the git-flow integration setup in the Docker container, which lets you execute git flow commands on the terminal rather than git commands directly.

The project also utilizes githooks to enforce gitflow and prevent users from accidently pushing to the main branch.

Plase read the following article for a sufficient introduction to the Gitflow Workflow: https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow.

Commitizen

This project uses githooks to enforce standarized commits according to the Commitizen style. Running git commit on the command line instigates a series of prompts guiding you through the standard.

Diagramming

All diagrams should be included on the repository to which they pertain. We use PlantUML to build all of our diagrams. PlantUML has a Domain Specific Language (DSL) for declaratively building various types of diagrams. You can write a .wsd, .pu, .puml, .plantuml, or .iuml file containing PlantUML DSL and the PlantUML Extension will enable you to render that diagram in a live preview by pressing Alt + D.

Workflow Automation

This repository uses Github Actions for several workflow automations as well as several organizational Github Integrations.

CI

Pre-commit githooks lint the codebase and then run all the project's mocha tests to prevent regressions from even being checked into the codebase. On top of this, the Test Action runs the project's mocha tests to check PRs before they are merged.

CD

The Release Action triggers on commits to the main branch utilzing the repository's Commitizen commit style to automatically version published code according to SemVar. The Release Action also publishes the project to our private npmjs repository scoped under @minimap-inc.

This repository also makes use of the Semantic Pull Probot to vet and squash the commits of merged PRs onto the main branch. For more information, see Semantic Release.

Dependency Management

The Renovate integration will periodically make PRs suggesting modifications to the dependecy structure to eliminiate vulnerabilities, update depricated dependencies, and perform other miscellenous tasks.

Static Code Analysis

The Accuracies integration analyzes the codebase for policy violations and vulnerabilities with the use of Cloud infrastructure (AWS, GCP, etc.) and makes PRs to corrct any detected issues before they become a problem.

License

Distributed under the Creative Commons Attribution-NoDerivatives 4.0 International License. See LICENSE for more information.