New code repository

• Make sure code goes through CI on every commit/merge
  • Use GitHub actions for this
    • Ensure ongoing runs are cancelled when a new one is triggered:

concurrency:
  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
  cancel-in-progress: ${{ github.ref != 'refs/heads/main' && !contains(github.event.pull_request.labels.*.name, 'ci:full') }}

• Run tests, linters, check formatting
• Have a .editorconfig
• Make sure your dependencies are up to date using Dependabot
  • Use groups https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#example-1
• Use a service like https://sonarcloud.io/ to help maintain code quality
• Use https://semgrep.dev/docs/getting-started/quickstart to find bugs and prevent vulnerabilities
• Write commits using the passive voice, e.g.
  • Snapshot interval build argument overrides any snapshot interval declared by the class macro
  • EntityStore build method records the specifier argument when given
  • Category macro is optional on EntityStore when a category is given to the constructor
  • Tests are clarified
  • Category can be configured when constructing a store
  • Category declaration test is moved
  • Specifier can be configured when constructing a store
  • Specifier macro is implemented
  • Instance configure is invoked before the instance is assured
  • Instance configure template method called from constructor
  • Store’s project method is an alias for fetch
  • Title is changed
  • Parenthesis are added to assert_raises and refute_raises
  • Automated test runner supplies exclude file pattern directly into CLI
  • Test files are compatible with TestBench 2.0
  • Unbalanced parenthesis in a log output is corrected
  • Log tags are standardized
  • Library-level log tags reduced to ‘entity_store’
  • Snapshot classes must implement assurance
  • Snapshot implementation assures snapshot
  • Default batch size is sourced from reader class
  • Default reader batch size is 1000
  • Superfluous test details are removed
  • Update of entity in substitute is tested
  • Updating substitute with new entity is tested⠀

Application repository 🔗

• In every repository of a service there is a swagger documentation, which can be accessed by the service over /docs
• In every repository of a service there is a README to describe all environment variables, how to start the service properly on every machine, and explain shortly in 2-3 sentences what the service does
• There is another repository called documentation, which has PlantUML files. A quick command to render all files is written in a Makefile.
• In the documentation repository there is a brief overview of all services as an object-diagram
• If there are complicated business processes going on over several services or within a service make a sequence-diagram
• If an application or a model has a state and is modified with events or procedural code: make a state-diagram
• If something in the services or processes changes, make a definition of done, if documentation was properly adapted
• I would avoid comments in the code as much as I can, mostly I just add a comment if there is a really complicated algorithm going on or an unexpected behavior, which could be deleted by another programmer in the project
• Yes documentation is annoying and yes it consumes much time, therefore you have to balance between “too much” and “too little” documentation
• Split your tests based on speed (Fast + Slow)
  • In local development fast tests are executed
    • Slow tests are executed optionally (e.g. if an ENV var is set e.g. SLOW_TESTS=1 make test)
  • In CI both fast and slow tests are executed
• Delete all your flaky tests

Public repository 🔗

• Consider using BreakVer over SemVer
  • https://www.taoensso.com/break-versioning
• Display the relevant badges for the repository
  • [![Tests](<https://github.com/user/repository/actions/workflows/tests.yaml/badge.svg>)](<https://github.com/user/repository/actions/workflows/tests.yaml>)
  • https://codecov.io/
  • https://goreportcard.com/
  • https://shields.io/badges/git-hub-go-mod-go-version
  • https://pkg.go.dev/ badge
    • https://pkg.go.dev/github.com/stretchr/testify
    • [![PkgGoDev](https://pkg.go.dev/badge/github.com/stretchr/testify)](https://pkg.go.dev/github.com/stretchr/testify)
  • https://0dependencies.dev/
• Pick a license
  • Usually MIT or Apache-2
• Maintain a CONTRIBUTING.md file
• Maintain a CHANGELOG.md file
  • https://keepachangelog.com/en/1.0.0/
• Have a code of conduct once/if the project becomes large (maybe even start with one)
• Public documentation
  • https://www.mkdocs.org/
  • https://github.com/squidfunk/mkdocs-material
    • Diataxis: A systematic approach to technical documentation authoring
      • https://blog.sequinstream.com/we-fixed-our-documentation-with-the-diataxis-framework/