|
| 1 | +# I don't want to read this whole thing I just have a question!!! |
| 2 | + |
| 3 | +> Note: Please don't file an issue to ask a question. |
| 4 | +
|
| 5 | +You'll get faster results by using our official [Gitter channel](https://gitter.im/json-api-dotnet-core/Lobby) or [StackOverflow](https://stackoverflow.com/search?q=jsonapidotnetcore) where the community chimes in with helpful advice if you have questions. |
| 6 | + |
| 7 | +# How can I contribute? |
| 8 | + |
| 9 | +## Reporting bugs |
| 10 | + |
| 11 | +This section guides you through submitting a bug report. |
| 12 | +Following these guidelines helps maintainers and the community understand your report, reproduce the behavior and find related reports. |
| 13 | + |
| 14 | +Before creating bug reports: |
| 15 | +- Perform a search to see if the problem has already been reported. If it has and the issue is still open, add a comment to the existing issue instead of opening a new one. If you find a Closed issue that seems like it is the same thing that you're experiencing, open a new issue and include a link to the original issue in the body of your new one. |
| 16 | +- Clone the source and run the project locally. You might be able to find the cause of the problem and fix things yourself. Most importantly, check if you can reproduce the problem in the latest version of the master branch. |
| 17 | + |
| 18 | +When you are creating a bug report, please include as many details as possible. |
| 19 | +Fill out the issue template, the information it asks for helps us resolve issues faster. |
| 20 | + |
| 21 | +### How do I submit a (good) bug report? |
| 22 | + |
| 23 | +Bugs are tracked as [GitHub issues](https://github.com/json-api-dotnet/JsonApiDotNetCore/issues). Create an issue and provide the following information by filling in the template. |
| 24 | +Explain the problem and include additional details to help maintainers reproduce the problem: |
| 25 | + |
| 26 | +- **Use a clear and descriptive title** for the issue to identify the problem. |
| 27 | +- **Describe the exact steps which reproduce the problem** in as many details as possible. When listing steps, don't just say what you did, but explain how you did it. |
| 28 | +- **Provide specific examples to demonstrate the steps.** Include links to files or GitHub projects, or copy/pasteable snippets, which you use in those examples. If you're providing snippets in the issue, use [Markdown code blocks](https://docs.github.com/en/github/writing-on-github/creating-and-highlighting-code-blocks). |
| 29 | +- **Describe the behavior you observed after following the steps** and point out what exactly is the problem with that behavior. Explain which behavior you expected to see instead and why. |
| 30 | +- **If you're reporting a crash**, include the full exception stack trace. |
| 31 | + |
| 32 | +## Suggesting enhancements |
| 33 | + |
| 34 | +This section guides you through submitting an enhancement suggestion, including completely new features and minor improvements to existing functionality. Following these guidelines helps maintainers and the community understand your suggestion and find related suggestions. |
| 35 | + |
| 36 | +Before creating enhancement suggestions: |
| 37 | +- Check the [documentation](https://www.jsonapi.net/usage/resources/index.html) and [integration tests](https://github.com/json-api-dotnet/JsonApiDotNetCore/tree/master/test/JsonApiDotNetCoreExampleTests/IntegrationTests) for existing features. You might discover the enhancement is already available. |
| 38 | +- Perform a search to see if the feature has already been reported. If it has and the issue is still open, add a comment to the existing issue instead of opening a new one. |
| 39 | + |
| 40 | +When you are creating an enhancement suggestion, please include as many details as possible. Fill in the template, including the steps that you imagine you would take if the feature you're requesting existed. |
| 41 | + |
| 42 | +- **Use a clear and descriptive title** for the issue to identify the suggestion. |
| 43 | +- **Provide a step-by-step description of the suggested enhancement** in as many details as possible. |
| 44 | +- **Provide specific examples to demonstrate the usage.** Include copy/pasteable snippets which you use in those examples, as [Markdown code blocks](https://docs.github.com/en/github/writing-on-github/creating-and-highlighting-code-blocks). |
| 45 | +- **Describe the current behavior and explain which behavior you expected to see instead** and why. |
| 46 | +- **Explain why this enhancement would be useful** to most users and isn't something that can or should be implemented in your API project directly. |
| 47 | +- **Verify that your enhancement does not conflict** with the [JSON:API specification](https://jsonapi.org/). |
| 48 | + |
| 49 | +## Your first code contribution |
| 50 | + |
| 51 | +Unsure where to begin contributing? You can start by looking through these [beginner](https://github.com/json-api-dotnet/JsonApiDotNetCore/labels/good%20first%20issue) and [help-wanted](https://github.com/json-api-dotnet/JsonApiDotNetCore/labels/help%20wanted) issues. |
| 52 | + |
| 53 | +## Pull requests |
| 54 | + |
| 55 | +Please follow these steps to have your contribution considered by the maintainers: |
| 56 | + |
| 57 | +- **The worst thing in the world is opening a PR that gets rejected** after you've put a lot of effort in it. So for any non-trivial changes, open an issue first to discuss your approach and ensure it fits the product vision. |
| 58 | +- Follow all instructions in the template. Don't forget to add tests and update documentation. |
| 59 | +- After you submit your pull request, verify that all status checks are passing. In release builds, all compiler warnings are treated as errors, so you should address them before push. |
| 60 | + |
| 61 | +We use [CSharpGuidelines](https://csharpcodingguidelines.com/) as our coding standard (with a few minor exceptions). Coding style is validated during PR build, where we inject an extra settings layer that promotes various suggestions to warning level. This ensures a high-quality codebase without interfering too much when editing code. |
| 62 | +You can run the following [PowerShell scripts](https://github.com/PowerShell/PowerShell/releases) locally: |
| 63 | +- `inspectcode.ps1`: Scans the code for style violations and opens the result in your web browser. |
| 64 | +- `cleanupcode.ps1` Reformats the entire codebase to match with our configured style. |
| 65 | + |
| 66 | +Code inspection violations can be addressed in several ways, depending on the situation: |
| 67 | +- Types that are reported to be never instantiated (because the IoC container creates them dynamically) should be decorated with `[UsedImplicitly(ImplicitUseKindFlags.InstantiatedNoFixedConstructorSignature)]`. |
| 68 | +- Exposed models that contain members never being read/written/assigned to should be decorated with `[UsedImplicitly(ImplicitUseTargetFlags.Members)]`. |
| 69 | +- Types that are part of our public API surface can be decorated with `[PublicAPI]`. This suppresses messages such as "type can be marked sealed/internal", "virtual member is never overridden", "member is never used" etc. |
| 70 | +- Incorrect violations can be [suppressed](https://www.jetbrains.com/help/resharper/Code_Analysis__Code_Inspections.html#ids-of-code-inspections) using a code comment. |
| 71 | + |
| 72 | +In few cases, the automatic reformat decreases the readability of code. For example, when calling a Fluent API using chained method calls. This can be prevented using [formatter directives](https://www.jetbrains.com/help/resharper/Enforcing_Code_Formatting_Rules.html#configure): |
| 73 | + |
| 74 | +```c# |
| 75 | +public sealed class AppDbContext : DbContext |
| 76 | +{ |
| 77 | + protected override void OnModelCreating(ModelBuilder builder) |
| 78 | + { |
| 79 | + // @formatter:wrap_chained_method_calls chop_always |
| 80 | +
|
| 81 | + builder.Entity<MusicTrack>() |
| 82 | + .HasOne(musicTrack => musicTrack.Lyric) |
| 83 | + .WithOne(lyric => lyric.Track) |
| 84 | + .HasForeignKey<MusicTrack>(); |
| 85 | + |
| 86 | + // @formatter:wrap_chained_method_calls restore |
| 87 | + } |
| 88 | +} |
| 89 | +``` |
| 90 | + |
| 91 | +## Backporting and hotfixes (for maintainers) |
| 92 | + |
| 93 | +- Checkout the version you want to apply the feature on top of and create a new branch to release the new version: |
| 94 | + ``` |
| 95 | + git checkout tags/v2.5.1 -b release/2.5.2 |
| 96 | + ``` |
| 97 | +- Cherrypick the merge commit: `git cherry-pick {git commit SHA}` |
| 98 | +- Bump the package version in the csproj |
| 99 | +- Make any other compatibility, documentation or tooling related changes |
| 100 | +- Push the branch to origin and verify the build |
| 101 | +- Once the build is verified, create a GitHub release, tagging the release branch |
| 102 | +- Open a PR back to master with any other additions |
0 commit comments