Skip to content

Commit 73fd72e

Browse files
benjirobenjiro
authored
Merge pull request #41 from open-feature/chore/update-readme-doco
chore: update readme
2 parents 45eaa44 + 279737a commit 73fd72e

File tree

3 files changed

+227
-3
lines changed

3 files changed

+227
-3
lines changed

‎CONTRIBUTING.md

+105
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
# Contributing to the OpenFeature project
2+
3+
## Development
4+
5+
You can contribute to this project from a Windows, macOS or Linux machine.
6+
7+
On all platforms, the minimum requirements are:
8+
9+
* Git client and command line tools.
10+
* .netstandard 2.0 or higher capable dotnet sdk (.Net Framework 4.6.2 or higher/.Net Core 3 or higher).
11+
12+
### Linux or MacOS
13+
14+
* Jetbrains Rider 2022.2+ or Visual Studio 2022+ for Mac or Visual Studio Code
15+
16+
### Windows
17+
18+
* Jetbrains Rider 2022.2+ or Visual Studio 2022+ or Visual Studio Code
19+
* .NET Framework 4.6.2+
20+
21+
## Pull Request
22+
23+
All contributions to the OpenFeature project are welcome via GitHub pull requests.
24+
25+
To create a new PR, you will need to first fork the GitHub repository and clone upstream.
26+
27+
```bash
28+
git clone https://github.com/open-feature/dotnet-sdk.git openfeature-dotnet-sdk
29+
```
30+
31+
Navigate to the repository folder
32+
```bash
33+
cd openfeature-dotnet-sdk
34+
```
35+
36+
Add your fork as an origin
37+
```bash
38+
git remote add fork https://github.com/YOUR_GITHUB_USERNAME/dotnet-sdk.git
39+
```
40+
41+
Makes sure your development environment is all setup by building and testing
42+
```bash
43+
dotnet build
44+
dotnet test
45+
```
46+
47+
To start working on a new feature or bugfix, create a new branch and start working on it.
48+
49+
```bash
50+
git checkout -b feat/NAME_OF_FEATURE
51+
# Make your changes
52+
git commit
53+
git push fork feat/NAME_OF_FEATURE
54+
```
55+
56+
Open a pull request against the main dotnet-sdk repository.
57+
58+
### How to Receive Comments
59+
60+
* If the PR is not ready for review, please mark it as
61+
[`draft`](https://github.blog/2019-02-14-introducing-draft-pull-requests/).
62+
* Make sure all required CI checks are clear.
63+
* Submit small, focused PRs addressing a single concern/issue.
64+
* Make sure the PR title reflects the contribution.
65+
* Write a summary that helps understand the change.
66+
* Include usage examples in the summary, where applicable.
67+
68+
### How to Get PRs Merged
69+
70+
A PR is considered to be **ready to merge** when:
71+
72+
* Major feedbacks are resolved.
73+
* It has been open for review for at least one working day. This gives people
74+
reasonable time to review.
75+
* Trivial change (typo, cosmetic, doc, etc.) doesn't have to wait for one day.
76+
* Urgent fix can take exception as long as it has been actively communicated.
77+
78+
Any Maintainer can merge the PR once it is **ready to merge**. Note, that some
79+
PRs may not be merged immediately if the repo is in the process of a release and
80+
the maintainers decided to defer the PR to the next release train.
81+
82+
If a PR has been stuck (e.g. there are lots of debates and people couldn't agree
83+
on each other), the owner should try to get people aligned by:
84+
85+
* Consolidating the perspectives and putting a summary in the PR. It is
86+
recommended to add a link into the PR description, which points to a comment
87+
with a summary in the PR conversation.
88+
* Tagging subdomain experts (by looking at the change history) in the PR asking
89+
for suggestion.
90+
* Reaching out to more people on the [CNCF OpenFeature Slack channel](https://cloud-native.slack.com/archives/C0344AANLA1).
91+
* Stepping back to see if it makes sense to narrow down the scope of the PR or
92+
split it up.
93+
* If none of the above worked and the PR has been stuck for more than 2 weeks,
94+
the owner should bring it to the OpenFeatures [meeting](README.md#contributing).
95+
96+
## Design Choices
97+
98+
As with other OpenFeature SDKs, dotnet-sdk follows the
99+
[openfeature-specification](https://github.com/open-feature/spec).
100+
101+
## Style Guide
102+
103+
This project includes a [`.editorconfig`](./.editorconfig) file which is
104+
supported by all the IDEs/editor mentioned above. It works with the IDE/editor
105+
only and does not affect the actual build of the project.

‎OpenFeature.SDK.sln

+2
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,8 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "build", "build", "{72005F60
1414
.github\workflows\linux-ci.yml = .github\workflows\linux-ci.yml
1515
.github\workflows\release-package.yml = .github\workflows\release-package.yml
1616
.github\workflows\windows-ci.yml = .github\workflows\windows-ci.yml
17+
README.md = README.md
18+
CONTRIBUTING.md = CONTRIBUTING.md
1719
EndProjectSection
1820
EndProject
1921
Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "src", "src", "{C97E9975-E10A-4817-AE2C-4DD69C3C02D4}"

‎README.md

+120-3
Original file line numberDiff line numberDiff line change
@@ -18,18 +18,131 @@ The packages will aim to support all current .NET versions. Refer to the current
1818
| ----------- | ----------- |
1919
| TBA | TBA |
2020

21-
## Basic Usage
21+
## Getting Started
22+
23+
### Basic Usage
2224

2325
```csharp
2426
using OpenFeature.SDK;
2527

28+
// Sets the provider used by the client
2629
OpenFeature.Instance.SetProvider(new NoOpProvider());
30+
// Gets a instance of the feature flag client
2731
var client = OpenFeature.Instance.GetClient();
28-
32+
// Evaluation the `my-feature` feature flag
2933
var isEnabled = await client.GetBooleanValue("my-feature", false);
3034
```
3135

32-
## Contributors
36+
### Provider
37+
38+
To develop a provider, you need to create a new project and include the OpenFeature SDK as a dependency. This can be a new repository or included in an existing contrib repository available under the OpenFeature organization. Finally, you’ll then need to write the provider itself. In most languages, this can be accomplished by implementing the provider interface exported by the OpenFeature SDK.
39+
40+
Example of implementing a feature flag provider
41+
42+
```csharp
43+
using OpenFeature.SDK;
44+
using OpenFeature.SDK.Model;
45+
46+
public class MyFeatureProvider : FeatureProvider
47+
{
48+
public static string Name => "My Feature Provider";
49+
50+
public Metadata GetMetadata()
51+
{
52+
return new Metadata(Name);
53+
}
54+
55+
public Task<ResolutionDetails<bool>> ResolveBooleanValue(string flagKey, bool defaultValue,
56+
EvaluationContext context = null,
57+
FlagEvaluationOptions config = null)
58+
{
59+
// code to resolve boolean details
60+
}
61+
62+
public Task<ResolutionDetails<string>> ResolveStringValue(string flagKey, string defaultValue,
63+
EvaluationContext context = null,
64+
FlagEvaluationOptions config = null)
65+
{
66+
// code to resolve string details
67+
}
68+
69+
public Task<ResolutionDetails<int>> ResolveIntegerValue(string flagKey, int defaultValue,
70+
EvaluationContext context = null,
71+
FlagEvaluationOptions config = null)
72+
{
73+
// code to resolve integer details
74+
}
75+
76+
public Task<ResolutionDetails<double>> ResolveDoubleValue(string flagKey, double defaultValue,
77+
EvaluationContext context = null,
78+
FlagEvaluationOptions config = null)
79+
{
80+
// code to resolve integer details
81+
}
82+
83+
public Task<ResolutionDetails<T>> ResolveStructureValue<T>(string flagKey, T defaultValue,
84+
EvaluationContext context = null,
85+
FlagEvaluationOptions config = null)
86+
{
87+
// code to resolve object details
88+
}
89+
}
90+
```
91+
92+
### Hook
93+
94+
Hooks are a mechanism that allow for the addition of arbitrary behavior at well-defined points of the flag evaluation life-cycle. Use cases include validation of the resolved flag value, modifying or adding data to the evaluation context, logging, telemetry, and tracking.
95+
96+
Example of adding a hook
97+
98+
```csharp
99+
// add a hook globally, to run on all evaluations
100+
openFeature.AddHooks(new ExampleGlobalHook());
101+
102+
// add a hook on this client, to run on all evaluations made by this client
103+
var client = OpenFeature.Instance.GetClient();
104+
client.AddHooks(new ExampleClientHook());
105+
106+
// add a hook for this evaluation only
107+
var value = await client.GetBooleanValue("boolFlag", false, context, new FlagEvaluationOptions(new ExampleInvocationHook()));
108+
```
109+
110+
Example of implementing a hook
111+
112+
```csharp
113+
public class MyHook : Hook
114+
{
115+
public Task<EvaluationContext> Before<T>(HookContext<T> context,
116+
IReadOnlyDictionary<string, object> hints = null)
117+
{
118+
// code to run before flag evaluation
119+
}
120+
121+
public virtual Task After<T>(HookContext<T> context, FlagEvaluationDetails<T> details,
122+
IReadOnlyDictionary<string, object> hints = null)
123+
{
124+
// code to run after successful flag evaluation
125+
}
126+
127+
public virtual Task Error<T>(HookContext<T> context, Exception error,
128+
IReadOnlyDictionary<string, object> hints = null)
129+
{
130+
// code to run if there's an error during before hooks or during flag evaluation
131+
}
132+
133+
public virtual Task Finally<T>(HookContext<T> context, IReadOnlyDictionary<string, object> hints = null)
134+
{
135+
// code to run after all other stages, regardless of success/failure
136+
}
137+
}
138+
```
139+
140+
## Contributing
141+
142+
See [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to contribute to the OpenFeature project.
143+
144+
Our community meetings are held regularly and open to everyone. Check the [OpenFeature community calendar](https://calendar.google.com/calendar/u/0?cid=MHVhN2kxaGl2NWRoMThiMjd0b2FoNjM2NDRAZ3JvdXAuY2FsZW5kYXIuZ29vZ2xlLmNvbQ) for specific dates and for the Zoom meeting links.
145+
33146

34147
Thanks so much for your contributions to the OpenFeature project.
35148

@@ -38,3 +151,7 @@ Thanks so much for your contributions to the OpenFeature project.
38151
</a>
39152

40153
Made with [contrib.rocks](https://contrib.rocks).
154+
155+
## License
156+
157+
[Apache License 2.0](LICENSE)

0 commit comments

Comments
 (0)