You can contribute to --INSERT PROJ NAME-- with issues and PRs. Simply filing issues for problems you encounter is a great way to contribute. Contributing implementations is greatly appreciated.
The codebase uses .net core coding style.
Try to keep lines of code around 100 characters in length or less, though this is not a hard limit. If you're a few characters over then don't worry too much.
We always welcome bug reports, API proposals and overall feedback. Here are a few tips on how you can make reporting your issue as effective as possible.
Before filing a new issue, please search our open issues to check if it already exists.
If you do find an existing issue, please include your own feedback in the discussion. Do consider upvoting (👍 reaction) the original post, as this helps us prioritize popular issues in my backlog.
Good bug reports make it easier for maintainers to verify and root cause the underlying problem. The better a bug report, the faster the problem will be resolved. Ideally, a bug report should contain the following information:
- A high-level description of the problem.
- A minimal reproduction, i.e. the smallest size of code/configuration required to reproduce the wrong behavior.
- A description of the expected behavior, contrasted with the actual behavior observed.
- Information on the environment: OS/distro, CPU arch, SDK version, etc.
- Additional information, e.g. is it a regression from previous versions? are there any known workarounds?
When ready to submit a bug report, please use the Bug Report issue template.
A reproduction lets maintainers verify the presence of a bug, and diagnose the issue using a debugger. A minimal reproduction is the smallest possible console application demonstrating that bug. Minimal reproductions are generally preferable since they:
- Focus debugging efforts on a simple code snippet,
- Ensure that the problem is not caused by unrelated dependencies/configuration,
- Avoid the need to share production codebases.
In certain cases, creating a minimal reproduction might not be practical (e.g. due to nondeterministic factors, external dependencies). In such cases you would be asked to provide as much information as possible, for example by sharing a memory dump of the failing application. If maintainers are unable to root cause the problem, they might still close the issue as not actionable. While not required, minimal reproductions are strongly encouraged and will significantly improve the chances of your issue being prioritized and fixed by the maintainers.
The best way to create a minimal reproduction is gradually removing code and dependencies from a reproducing app, until the problem no longer occurs. A good minimal reproduction:
- Excludes all unnecessary types, methods, code blocks, source files, nuget dependencies and project configurations.
- Contains documentation or code comments illustrating expected vs actual behavior.
We use and recommend the following workflow:
- Create an issue for your work.
- You can skip this step for trivial changes.
- Reuse an existing issue on the topic, if there is one.
- Get agreement from the team and the community that your proposed change is a good one.
- Clearly state that you are going to take on implementing it, if that's the case. You can request that the issue be assigned to you. Note: The issue filer and the implementer don't have to be the same person.
- Create a personal fork of the repository on GitHub (if you don't already have one).
- In your fork, create a branch off of master (
git checkout -b mybranch).- Name the branch so that it clearly communicates your intentions, such as issue-123 or githubhandle-issue.
- Branches are useful since they isolate your changes from incoming changes from upstream. They also enable you to create multiple PRs from the same fork.
- Make and commit your changes to your branch.
- Please follow my Commit Messages guidance.
- Add new tests corresponding to your change, if applicable.
- Build the repository with your changes.
- Make sure that the builds are clean.
- Make sure that the tests are all passing, including your new tests.
- Create a pull request (PR) against the repository's master branch.
- State in the description what issue or improvement your change is addressing.
- Check if all the Continuous Integration checks are passing.
- Wait for feedback or approval of your changes.
Most straightforward issues as help wanted. This set of issues is the place to start if you are interested in contributing but new to the codebase.
There are one type of tests currently in the codebase; unit tests.
Unit tests should be contained in a class name that mirrors the class being tested with the suffix -Tests, e.g.
ArcadePointsBot.Tests.Services.RepoServiceTests
Where Arcade.ProjectTracker.Tests is the name of the project.
Unit test methods should be named in a sentence style, separated by underscores, that describes in English what the test is testing, e.g.
void Calling_Foo_Should_Increment_Bar()Please format commit messages as follows (based on A Note About Git Commit Messages):
Summarize change in 50 characters or less
Provide more detail after the first line. Leave one blank line below the
summary and wrap all lines at 72 characters or less.
If the change fixes an issue, leave another blank line after the final
paragraph and indicate which issue is fixed in the specific format
below.
Fix #42
Also do your best to factor commits appropriately, not too large with unrelated things in the same commit, and not too small with the same small change applied N times in N different commits.
This project has adopted the code of conduct defined by the Contributor Covenant to clarify expected behavior in our community. For more information see the Contributor Covenant Code of Conduct
Partially yoinked from dotnet/runtime