Skip to content

Contribution

This document describes how to contribute to nessy.

Contributions are warmly welcomed & therefore we want to make your life as easy as possible. For a guide on how to setup an optimal development environment, please refer to this documentation.

The perfect Pull Request

When contributing to Nessy, we follow to principle of "The perfect PR". This means, every PR includes:

  • The implementation: a single, focused change
  • Unit and Integration tests that demonstrate the implementation works
  • Updated documentation reflecting the change, check the Documentation Guide
  • A link to an Azure DevOps Workitem providing further context

This principle is derived from this blog post by Simon Willison.

Nessy aims to implement best practices across the board:

  • don't implement hacky code or workarounds, just to make things work.
  • every implemented Module, Function or Class should follow the unix principle "Make each program do one thing well. To do a new job, build afresh rather than complicate old programs by adding new features".
  • All code should follow a conscious decision about the vision and architecture of the framework.
  • When implementing new features a decision about why and where to implement them should be made and documented.
  • Standardized Logging to dynamic targets & helpful error handling are implemented.

Following these principles will allow us to easily maintain and extend the Framework going forward.

How To Contribute

When you start contributing to nessy, you can follow this process:

  graph TB;
    A[Open repo devcontainer] --> B[Checkout main] --> B1[Create Feature branch]
    B1 --> C[Build, Deploy, Test]
    C --> C
    C --> C1
    C1[Update the Version] --> D[Create Pull Request]
  1. Check the Development Environment Guide for instructions on how to setup the local development environment.
  2. The Feature branch should reference an item on the Azure DevOps board. The branch can then be created in the format feature/<dev_ops_item_number>_<description>, e.g. feature/123_transformer_sql.
  3. The implementation on your branch should follow the principles describes in the perfect PR-section.
  4. Find a description on how versioning works for nessy here.
  5. Once the Pull Request is created, the nessy Team will make sure to review it as soon as possible.

Branching

The branching-strategy for nessy is GitHub Flow also known as Feature Branch Flow. It involves creating a new branch for each feature or fix, committing changes to this branch, and opening a pull request for discussion and code review before merging it back into the main branch.

This process ensures that code is always in a deployable state and encourages team collaboration and code quality through peer reviews.

%%{init: { 'logLevel': 'debug', 'theme': 'default', 'themeVariables': {
    'commitLabelColor': '#ffffff',
    'git0': '#909590',
    'git1': '#537A5A',
    'git2': '#C21807',
    'commitLabelBackground': '#4CAF50'
} } }%%
gitGraph
   commit id: "main"
   branch feature/1_update_models
   commit id: "start table model"
   checkout "main"
   commit id: "other feature merged"
   branch feature/2_implement_parser
   commit id: "start sql parser"
   checkout feature/1_update_models
   checkout feature/2_implement_parser
   commit id: "work on sql parser"
   checkout feature/1_update_models
   commit id: "more work on column model"
   checkout main
   merge feature/1_update_models
   commit id: "merge feature1"
   merge feature/2_implement_parser
   commit id: "merge feature2"

Explanation:

  • Start: Update the main branch.
  • Feature Branches: Create feature branch from main.
  • Parallel Work: Both branches proceed with independent commits.
  • Merge: Finally, merge features back into main.

Versioning

nessy follows a semantic versioning approach. Versions are created in the format major.minor.patch, e.g. 1.12.123.

When to indent the versions? - major: The new version introduces major or breaking changes. - minor: New features are implemented. - patch: Updates that implement fixes to existing features and small improvements.

If the version is created from a branch other than main, the version must be suffixed with beta, this is done by the CI-Pipeline automatically and prevents users from installing a work-in-progress-version, unless they explicitly specify it.