Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
175 lines (119 loc) · 7.57 KB

CONTRIBUTING.md

File metadata and controls

175 lines (119 loc) · 7.57 KB

Contributing

System Requirements

Dotnet 8+ is recommended.

Development Environment

Dev Container

This repository includes a Dev Container configuration that provides a fully configured development environment with all necessary tools and extensions pre-installed.

Prerequisites

Getting Started with Dev Container

  1. Clone the repository
  2. Open the repository in VS Code
  3. When prompted, click "Reopen in Container" or run the command Dev Containers: Reopen in Container from the Command Palette (F1)
  4. Wait for the container to build and start (this may take a few minutes the first time)

The Dev Container includes:

  • .NET SDK 10.0 with .NET 9.0 and 8.0 runtimes
  • GitHub CLI
  • Docker-in-Docker support for running E2E tests
  • Recommended VS Code extensions for C# development

Manual Setup

If you prefer not to use the Dev Container, ensure you have the following installed:

  • .NET SDK 10.0 or later
  • Docker (for running E2E tests)

Adding a project

  1. Create a new library project under src/: dotnet new classlib -o src/OpenFeature.MyComponent
  2. Create a new test project under test/: dotnet new xunit -o test/OpenFeature.MyComponent.Test
  3. Add the library project to the solution: dotnet sln DotnetSdkContrib.slnx add src/OpenFeature.MyComponent/OpenFeature.MyComponent.csproj
  4. Add the test project to the solution: dotnet sln DotnetSdkContrib.slnx add test/OpenFeature.MyComponent.Test/OpenFeature.MyComponent.Test.csproj
  5. Add the desired properties to your library's .csproj file (see example below).
  6. Remove all content besides the root element from your test project's .csproj file (all settings will be inherited).
  7. Add the new library project to release-please-config.json.
  8. Add a version.txt file to the root of your library with a version matching that in your new .csproj file, e.g. 0.0.1.
  9. If you care to release a pre 1.0.0 version, add the same version above to .release-please-manifest.json. Failing to do this will release a 1.0.0 initial release.

Sample .csproj file:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <PackageId>OpenFeature.MyComponent</PackageId>
    <VersionNumber>0.0.1</VersionNumber> <!--x-release-please-version -->
    <VersionPrefix>$(VersionNumber)</VersionPrefix>
    <AssemblyVersion>$(VersionNumber)</AssemblyVersion>
    <FileVersion>$(VersionNumber)</FileVersion>
    <Description>A very valuable OpenFeature contribution!</Description>
    <Authors>Me!</Authors>
  </PropertyGroup>

</Project>

Documentation

Any published modules must have documentation in their root directory, explaining the basic purpose of the module as well as installation and usage instructions. Instructions for how to develop a module should also be included (required system dependencies, instructions for testing locally, etc).

Testing

Any published modules must have reasonable test coverage. The instructions above will generate a test project for you.

Use dotnet test to test the entire project.

Running End-to-End (E2E) Integration Tests

To run the E2E integration tests for this repository, you need to set up your development environment as follows:

Prerequisites

  • Docker: You must have Docker installed and running on your machine. You can use Docker Desktop for Windows or install Docker on Linux/Mac OS. The E2E tests require Docker to spin up test containers.

Configuration

Each E2E test project contains an appsettings.json file. To enable E2E tests, ensure the following setting is present and set to true:

{
  "E2E": "true"
}

You can also set the E2E environment variable to true if you prefer not to modify the appsettings.json file.

An example E2E project are the Flagd Provider E2E tests, found here.

If you want to disable E2E tests, set "E2E": "false" or remove the setting.

Note: The E2E tests will be skipped if Docker is not running or if the E2E setting is not enabled in appsettings.json.

Automated Changelog

Each time a release is published the changelogs will be generated automatically using googleapis/release-please-action. The tool will organise the changes based on the PR labels. Please make sure you follow the latest conventions. We use an automation to check if the pull request respects the desired conventions. You can check it here. Must be one of the following:

  • build: Changes that affect the build system or external dependencies (example scopes: nuget)
  • ci: Changes to our CI configuration files and scripts (example scopes: GitHub Actions, Coverage)
  • docs: Documentation only changes
  • feat: A new feature
  • fix: A bug fix
  • perf: A code change that improves performance
  • refactor: A code change that neither fixes a bug nor adds a feature
  • style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
  • test: Adding missing tests or correcting existing tests

If you want to point out a breaking change, you should use ! after the type. For example: feat!: excellent new feature.

Changelog Visibility and Release Triggers

Only certain types are visible in the generated changelog:

  • feat: ✨ New Features - New functionality added
  • fix: 🐛 Bug Fixes - Bug fixes and corrections
  • perf: 🚀 Performance - Performance improvements
  • refactor: 🔧 Refactoring - Code changes that neither fix bugs nor add features
  • revert: 🔙 Reverts - Reverted changes

Dependencies

Keep dependencies to a minimum. Dependencies used only for building and testing should have a <PrivateAssets>all</PrivateAssets> element to prevent them from being exposed to consumers.

Consuming pre-release packages

  1. Acquire a GitHub personal access token (PAT) scoped for read:packages and verify the permissions:

    $ gh auth login --scopes read:packages

? What account do you want to log into? GitHub.com
? What is your preferred protocol for Git operations? HTTPS
? How would you like to authenticate GitHub CLI? Login with a web browser

! First copy your one-time code: ****-****
Press Enter to open github.com in your browser...

✓ Authentication complete.
- gh config set -h github.com git_protocol https
✓ Configured git protocol
✓ Logged in as ********
    $ gh auth status

github.com
  ✓ Logged in to github.com as ******** (~/.config/gh/hosts.yml)
  ✓ Git operations for github.com configured to use https protocol.
  ✓ Token: gho_************************************
  ✓ Token scopes: gist, read:org, read:packages, repo, workflow

  2. Run the following command to configure your local environment to consume packages from GitHub Packages:

    $ dotnet nuget update source github-open-feature --username $(gh api user --jq .email) --password $(gh auth token) --store-password-in-clear-text

Package source "github-open-feature" was successfully updated.