You can file an issue to ask a question, but you'll get faster results by using our official Gitter channel or StackOverflow where the community chimes in with helpful advice if you have questions.
This section guides you through submitting a bug report. Following these guidelines helps maintainers and the community understand your report, reproduce the behavior and find related reports.
Before creating bug reports:
- 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.
- 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.
When you are creating a bug report, please include as many details as possible. Fill out the issue template, the information it asks for helps us resolve issues faster.
Bugs are tracked as GitHub issues. Create an issue and provide the following information by filling in the template. Explain the problem and include additional details to help maintainers reproduce the problem:
- Use a clear and descriptive title for the issue to identify the problem.
- 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.
- 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.
- 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.
- If you're reporting a crash, include the full exception stack trace.
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.
Before creating enhancement suggestions:
- Check the documentation and integration tests for existing features. You might discover the enhancement is already available.
- 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.
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.
- Use a clear and descriptive title for the issue to identify the suggestion.
- Provide a step-by-step description of the suggested enhancement in as many details as possible.
- Provide specific examples to demonstrate the usage. Include copy/pasteable snippets which you use in those examples as Markdown code blocks.
- Describe the current behavior and explain which behavior you expected to see instead and why.
- 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.
- Verify that your enhancement does not conflict with the JSON:API specification.
Unsure where to begin contributing? You can start by looking through these beginner and help-wanted issues.
Please follow these steps to have your contribution considered by the maintainers:
- 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.
- Follow all instructions in the template. Don't forget to add tests and update documentation.
- 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.
We use CSharpGuidelines as our coding standard. Coding style is validated during PR build, where we inject an extra settings layer that promotes various IDE suggestions to warning level. This ensures a high-quality codebase without interfering too much while editing code. You can run the following PowerShell scripts locally:
pwsh ./inspectcode.ps1: Scans the code for style violations and opens the result in your web browser.pwsh ./cleanupcode.ps1 [branch-name-or-commit-hash]: Reformats the codebase to match with our configured style, optionally only changed files since the specified branch (usually master).
Code inspection violations can be addressed in several ways, depending on the situation:
- Types that are reported to be never instantiated (because the IoC container creates them dynamically) should be decorated with
[UsedImplicitly(ImplicitUseKindFlags.InstantiatedNoFixedConstructorSignature)]. - Exposed models that contain members never being read/written/assigned to should be decorated with
[UsedImplicitly(ImplicitUseTargetFlags.Members)]. - 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. - Incorrect violations can be suppressed using a code comment.
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:
public sealed class AppDbContext : DbContext
{
protected override void OnModelCreating(ModelBuilder builder)
{
// @formatter:wrap_chained_method_calls chop_always
builder.Entity<MusicTrack>()
.HasOne(musicTrack => musicTrack.Lyric)
.WithOne(lyric => lyric.Track)
.HasForeignKey<MusicTrack>();
// @formatter:wrap_chained_method_calls restore
}
}Please follow the steps and guidelines below for a smooth experience.
Authors:
- When opening a new pull request, create it in Draft mode.
- After you've completed the work and all checks are green, click the Ready for review button.
- If you have permissions to do so, ask a team member for review.
- Once the review has started, don't force-push anymore.
- When you've addressed feedback from a conversation, mark it with a thumbs-up or add a some text.
- Don't close a conversation you didn't start. The creator closes it after verifying the concern has been addressed.
- Apply suggestions in a batch, instead of individual commits (to minimize email notifications).
- Re-request review when you're ready for another round.
- If you want to clean up your commits before merge, let the reviewer know in time. This is optional.
Reviewers:
- If you're unable to review within a few days, let the author know what to expect.
- Use Start a review instead of Add single comment (to minimize email notifications).
- Consider to use suggestions (the ± button).
- Don't close a conversation you didn't start. Close the ones you opened after verifying the concern has been addressed.
- Once approved, use a merge commit only if all commits are clean. Otherwise, squash them into a single commit.
A commit is considered clean when:
- It is properly documented and covers all aspects of an isolated change (code, style, tests, docs).
- Checking out the commit results in a green build.
- Having this commit show up in the history is helpful (and can potentially be reverted).
- Verify documentation is up-to-date
- Bump the package version in
Directory.Build.props - Create a GitHub release
- Update JsonApiDotNetCore.MongoDb to consume the new version and release
- Create a new branch in MigrationGuide and update README.md in master, if major version change
- Checkout the version you want to apply the feature on top of and create a new branch to release the new version:
git checkout tags/v2.5.1 -b release/2.5.2 - Cherrypick the merge commit:
git cherry-pick {git commit SHA} - Bump the package version in
Directory.Build.props - Make any other compatibility, documentation, or tooling related changes
- Push the branch to origin and verify the build
- Once the build is verified, create a GitHub release, tagging the release branch
- Open a PR back to master with any other additions