Skip to content

docs: Update contributing guidelines #413

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Apr 1, 2025
Merged

docs: Update contributing guidelines #413

Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
a1345e4
docs: update contributing guidelines for .NET SDK version and formatting
askpt Mar 28, 2025
da6853c
docs: clarify E2E test setup instructions in contributing guidelines
askpt Mar 28, 2025
5c033a2
docs: update changelog generation tool and clarify conventions
askpt Mar 28, 2025
34448e8
Update CONTRIBUTING.md
askpt Mar 28, 2025
2ec0a61
docs: enhance contributing guidelines with detailed commit message co…
askpt Mar 28, 2025
df455ea
Update CONTRIBUTING.md
askpt Mar 28, 2025
2afcabd
docs: correct formatting and enhance clarity in contributing guidelines
askpt Mar 28, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
148 changes: 77 additions & 71 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,17 +6,17 @@ You can contribute to this project from a Windows, macOS or Linux machine.

On all platforms, the minimum requirements are:

* Git client and command line tools.
* .netstandard 2.0 or higher capable dotnet sdk (.Net Framework 4.6.2 or higher/.Net Core 3 or higher).
- Git client and command line tools.
- .netstandard 2.0 or higher capable dotnet sdk (.Net Framework 4.6.2 or higher/.Net 8 or higher).

### Linux or MacOS

* Jetbrains Rider 2022.2+ or Visual Studio 2022+ for Mac or Visual Studio Code
- JetBrains Rider 2022.2+ or Visual Studio 2022+ for Mac or Visual Studio Code

### Windows

* Jetbrains Rider 2022.2+ or Visual Studio 2022+ or Visual Studio Code
* .NET Framework 4.6.2+
- JetBrains Rider 2022.2+ or Visual Studio 2022+ or Visual Studio Code
- .NET Framework 4.6.2+

## Pull Request

Expand All @@ -29,11 +29,13 @@ git clone https://github.com/open-feature/dotnet-sdk.git openfeature-dotnet-sdk
```

Navigate to the repository folder

```bash
cd openfeature-dotnet-sdk
```

Add your fork as an origin

```bash
git remote add fork https://github.com/YOUR_GITHUB_USERNAME/dotnet-sdk.git
```
Expand Down Expand Up @@ -61,37 +63,37 @@ dotnet test test/OpenFeature.Tests/

#### E2E tests

To be able to run the e2e tests, first we need to initialize the submodule and copy the test files:
To be able to run the e2e tests, first we need to initialize the submodule.

```bash
git submodule update --init --recursive && cp spec/specification/assets/gherkin/evaluation.feature test/OpenFeature.E2ETests/Features/
git submodule update --init --recursive
```

Now you can run the tests using:
Since all the spec files are copied during the build process. Now you can run the tests using:

```bash
dotnet test test/OpenFeature.E2ETests/
```

### How to Receive Comments

* If the PR is not ready for review, please mark it as
[`draft`](https://github.blog/2019-02-14-introducing-draft-pull-requests/).
* Make sure all required CI checks are clear.
* Submit small, focused PRs addressing a single concern/issue.
* Make sure the PR title reflects the contribution.
* Write a summary that helps understand the change.
* Include usage examples in the summary, where applicable.
- If the PR is not ready for review, please mark it as
[`draft`](https://github.blog/2019-02-14-introducing-draft-pull-requests/).
- Make sure all required CI checks are clear.
- Submit small, focused PRs addressing a single concern/issue.
- Make sure the PR title reflects the contribution.
- Write a summary that helps understand the change.
- Include usage examples in the summary, where applicable.

### How to Get PRs Merged

A PR is considered to be **ready to merge** when:

* Major feedbacks are resolved.
* It has been open for review for at least one working day. This gives people
reasonable time to review.
* Trivial change (typo, cosmetic, doc, etc.) doesn't have to wait for one day.
* Urgent fix can take exception as long as it has been actively communicated.
- Major feedbacks are resolved.
- It has been open for review for at least one working day. This gives people
reasonable time to review.
- Trivial change (typo, cosmetic, doc, etc.) doesn't have to wait for one day.
- Urgent fix can take exception as long as it has been actively communicated.

Any Maintainer can merge the PR once it is **ready to merge**. Note, that some
PRs may not be merged immediately if the repo is in the process of a release and
Expand All @@ -100,32 +102,33 @@ the maintainers decided to defer the PR to the next release train.
If a PR has been stuck (e.g. there are lots of debates and people couldn't agree
on each other), the owner should try to get people aligned by:

* Consolidating the perspectives and putting a summary in the PR. It is
recommended to add a link into the PR description, which points to a comment
with a summary in the PR conversation.
* Tagging subdomain experts (by looking at the change history) in the PR asking
for suggestion.
* Reaching out to more people on the [CNCF OpenFeature Slack channel](https://cloud-native.slack.com/archives/C0344AANLA1).
* Stepping back to see if it makes sense to narrow down the scope of the PR or
split it up.
* If none of the above worked and the PR has been stuck for more than 2 weeks,
the owner should bring it to the OpenFeatures [meeting](README.md#contributing).
- Consolidating the perspectives and putting a summary in the PR. It is
recommended to add a link into the PR description, which points to a comment
with a summary in the PR conversation.
- Tagging subdomain experts (by looking at the change history) in the PR asking
for suggestion.
- Reaching out to more people on the [CNCF OpenFeature Slack channel](https://cloud-native.slack.com/archives/C0344AANLA1).
- Stepping back to see if it makes sense to narrow down the scope of the PR or
split it up.
- If none of the above worked and the PR has been stuck for more than 2 weeks,
the owner should bring it to the OpenFeatures [meeting](README.md#contributing).

## Automated Changelog

Each time a release is published the changelogs will be generated automatically using [dotnet-releaser](https://github.com/xoofx/dotnet-releaser/blob/main/doc/changelog_user_guide.md#13-categories). The tool will organise the changes based on the PR labels.
Each time a release is published the changelogs will be generated automatically using [googleapis/release-please-action](https://github.com/googleapis/release-please-action). The tool will organise the changes based on the PR labels.
Please make sure you follow the latest [conventions](https://www.conventionalcommits.org/en/v1.0.0/). We use an automation to check if the pull request respects the desired conventions. You can check it [here](https://github.com/open-feature/dotnet-sdk/actions/workflows/lint-pr.yml). 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

- 🚨 Breaking Changes = `breaking-change`
- ✨ New Features = `feature`
- 🐛 Bug Fixes = `bug`
- 🚀 Enhancements = `enhancement`
- 🧰 Maintenance = `maintenance`
- 🏭 Tests = `tests`, `test`
- 🛠 Examples = `examples`
- 📚 Documentation = `documentation`
- 🌎 Accessibility = `translations`
- 📦 Dependencies = `dependencies`
- 🧰 Misc = `misc`
If you want to point out a breaking change, you should use `!` after the type. For example: `feat!: excellent new feature`.

## Design Choices

Expand Down Expand Up @@ -153,34 +156,37 @@ dotnet release/OpenFeature.Benchmarks.dll
## Consuming pre-release packages

1. Acquire a [GitHub personal access token (PAT)](https://docs.github.com/github/authenticating-to-github/creating-a-personal-access-token) scoped for `read:packages` and verify the permissions:
```console
$ 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 ********
```

```console
$ 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
```

```console
$ 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 ********
```

```console
$ 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:
```console
$ 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.
```
```console
$ 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.
```