A collection of guidelines, best practices and tools used in development at Neoskop.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
configs
.gitignore
LICENSE
README.md

README.md

Neoskop Development Guidelines

A collection of guidelines, best practices and tools used in development at Neoskop.

Note: This repository serves as a living document, representing essential guidelines concerning our development workflow. Please use pull requests to keep this document up to date and challenge outdated or obsolete contents whenever you see fit.

Table of Contents

General Thoughts

  • When writing code we …

    • focus on code that gets the job done.
    • value comprehensibility and ease of maintenance over writing "clever code".
    • do not focus on perfect code, but code that strikes the best balance of value for our time.

Linting

We make sure to always lint our code before committing stuff to a repository. The sample configuration files in this repository could be taken as a fair starting point. Many rules are certainly a matter of taste, so feel free to adjust. Just make sure to include linting files in your repositories, so other developers can use it when jumping in your code.

  • JavaScript

    • We use ESLint as the linting tool for JavaScript and JSX.
    • Here is a possible configuration: eslint.json
  • TypeScript

    • We use TSLint as the linting tool for TypeScript.
    • We use codelyzer in our Angular projects.
    • Here is a possible configuration: tslint.json
  • CSS

⬆ back to top

Formatting

Automatic formatting of code makes it easier for other developers to navigate our code. We make sure our code gets formatted before committing changes to a repository.

  • JavaScript / TypeScript

    • We use Prettier to format our JavaScript/TypeScript code.
    • Our default configuration: .prettierrc
    • Do use the --single-quote option.
    • You may overwrite the --print-width <int> option.
    • Do not overwrite other options.
  • Java

  • HTML

    • For now, we don't use a formatter for HTML.
    • Feel free to evaluate possible options.
  • CSS

⬆ back to top

Build Tools / Libraries

  • JavaScript / TypeScript

    • We prefer Yarn as our package manager, due to its speed and "workspaces" feature used in our mono repos. We only use exact version numbers in our package.json (no ~ or ^).
    • We use Webpack as our code bundler.
    • For more advanced build steps we use NPM scripts. You may consider Jake for really complex build steps.
    • We use npm audit to monitor our dependencies for vulnerabilities in projects using NPM >= 6. Otherwise we use Snyk.
  • Angular

    • We use the Angular CLI to bootstrap new projects.
    • You may eject the project, if you need to customize the Webpack configuration.
    • Consider nrwl/nx for large scale applications.
  • React

    • We use create-react-app to bootstrap new projects.
    • You may eject the project, if you need to customize the Webpack configuration.
    • We are currently evaluating Next.js and react-static as our go-to-library for static site generation with React.
  • Styles

⬆ back to top

Testing

  • Whichever testing framework you use, you should be writing tests.
  • Strive for a good amount of test coverage.
  • Fixed a bug? Write a regression test to prevent it from breaking again.
  • We use Testcafe for our E2E tests.

⬆ back to top

Deployment

  • We use Docker to build and ship our applications and deploy our applications to Kubernetes.
    • We deliver a Dockerfile as well as a docker-compose.yml file for multi-container applications that is ready for use in development.
    • We commit the Kubernetes manifests we use to the same repository as the application's code.
    • To ensure that our applications keep running and don't impact others in the same cluster, our manifests include Readiness and Liveness probes as well as Resource requests and limits
    • We realize that containerizing an application is no silver bullet against security threats and thus use the CIS Docker CE Benchmark v1.1.0 / Docker Bench for Security to audit our images and containers
  • We use Buddy for continuous integration and continuous delivery. Integrate your tests with Buddy whenever possible to prevent corrupt deployments.

⬆ back to top

Versioning

  • Always have a .gitignore.
  • Do not commit sensitive data.
  • We use Karma's best practices for semantic commit messages. It makes scanning the log easier and allows for an easier generation of changelogs.
  • You may write commit messages in German or English, just be consistent throughout your projects.
  • Feel free to evaluate tools for optimized Git workflows, e.g. Gitflow.

⬆ back to top

Documentation

  • We write README files for all our projects.
  • Every developer should be able to run the application following the instructions in the README file.
  • Stick to easy step by step instructions and do not make assumptions about the user's foreknowledge.

⬆ back to top

Checklist

  • Linting
    • Are linting configuration files available and under version control?
      • JavaScript: eslint.json
      • TypeScript: tslint.json
      • Stylesheets: .stylelintrc
    • Is linting configured with your IDE?
  • Formatting
    • Is a Prettier configuration file available and under version control?
    • Is Prettier configured with your IDE?
  • Build Tools / Libraries
    • Are you using Yarn as the package manager?
      • Is the yarn.lock file under version control?
      • Are dependencies defined using exact version numbers (no ^ or ~ in version numbers)?
    • Are you using Webpack for bundling?
    • Are you using PostCSS with postcss-preset-env or LibSass for CSS transformations?
  • Testing
    • Did you configure automatic unit and e2e test suites?
  • Deployment
    • Are there working Docker files to run the application on server and locally?
    • Do the sources include recent and valid Kubernetes manifests to re-deploy the application from scratch?
    • Are Buddy build and deployment tasks available?
    • Have tests been integrated with Buddy?
  • Versioning
    • Is there a .gitignore excluding all neccessary files?
    • Did you make sure NOT to commit sensitive data?
    • Did you enforce semantic commit messages through commit hooks or the like?
  • Documentation
    • Did you write a README.md containing step by step instructions to run the application?

⬆ back to top