One of the easiest ways for you to contribute is to participate in discussions on GitHub issues. You can also contribute by submitting pull requests with code changes.
Start a discussion on the repository issue tracker.
For non-security related bugs, please log a new issue or simply click this link.
In order to get the source, clone the repo with submodules:
git clone https://github.com/dotnet/upgrade-assistant
git submodule update --init --recursive
The project is always targeting the latest SDK, so if you don't have that installed, you can set up a local dev environment by doing the following:
- Run
./build.batto ensure download the correct SDK - Launch
Microsoft.DotNet.UpgradeAssistant.slnfrom that directory
We are always happy to see PRs from community members both for bug fixes as well as new features. To help you be successful we've put together a few simple rules to follow when you prepare to contribute to our codebase:
Finding an issue to work on
We've created a separate bucket of issues, which would be great candidates for community members to contribute to. We mark these issues with the help wanted label. You can find all these issues here.
Within that set, we have additionally marked issues which are good candidates for first-time contributors. Those do not require too much familiarity with the codebase and are more novice-friendly. Those are marked with good first issue label. The full list of such issues can be found here.
If there is some other area not included here where you want to contribute to, first open an issue to describe the problem you are trying to solve and state that you're willing to contribute a fix for it. We will then discuss in that issue, if this is an issue we would like addressed and the best approach to solve it.
Before writing code
This can save you a lot of time. We've seen PRs where customers solve an issue in a way which either wouldn't fit into upgrade-assistant because of how it's designed or would change upgrade-assistant in a way which is not something we'd like to do. To avoid these situations, we encourage customers to discuss the preferred design with the team first. To do so, file a new design proposal issue, link to the issue you'd like to address and provide detailed information about how you'd like to solve a specific problem. We triage issues periodically and it will not take long for a team member to engage with you on that proposal.
When you get an agreement from our team members that the design proposal you have is solid, then go ahead and prepare the PR.
To file a design proposal, look for the relevant issue in the New issue page or simply click this link:
Before submitting the pull request
Before submitting a pull request, make sure that it checks the following requirements:
- You find an existing issue with the "help-wanted" label or discuss with the team to agree on adding a new issue with that label
- You post a high-level description of how it will be implemented, and receive a positive acknowledgement from the team before getting too committed to the approach or investing too much effort implementing it
- You add test coverage following existing patterns within the codebase
- Your code matches the existing syntax conventions within the codebase
- Your PR is small, focused, and avoids making unrelated changes
If your pull request contains any of the below, it's less likely to be merged:
- Changes that break existing functionality.
- Changes that are only wanted by one person/company. Changes need to benefit a large enough portion of upgrade-assistant users.
- Changes that add entirely new feature areas without prior agreement
- Changes that are mostly about refactoring existing code or code style
- Very large PRs that would take hours to review (remember, we're trying to help lots of people at once). For larger work areas, please discuss with us to find ways of breaking it down into smaller, incremental pieces that can go into separate PRs.
During pull request review A core contributor will review your pull request and provide feedback. To ensure that there is not a large backlog of inactive PRs, the pull request will be marked as stale after two weeks of no activity. After another four days, it will be closed.
Before contributing to Upgrade Assistant, you should be familiar with the logical components that comprise the tool and architecture validation processes, as described in the Upgrade Assistant architecture documentation.
Here are some resources to help you get started on how to contribute code or new content.
- Look at the Contributor documentation to get started on building the source code on your own.
- "Help wanted" issues - these issues are up for grabs. Comment on an issue if you want to create a fix.
- "Good first issue" issues - we think these are a good for newcomers.
- Best Practices for Roslyn Analyzers and Code Fixers - our goal is to build analyzers that are performant and available for both C# and Visual Basic by default.
If you would like to contribute to upgrade-assistant, first identify the scale of what you would like to contribute. If it is small (grammar/spelling or a bug fix) feel free to start working on a fix. If you are submitting a feature or substantial code contribution, please discuss it with the team and ensure it follows the product roadmap. You might also read these two blogs posts on contributing code: Open Source Contribution Etiquette by Miguel de Icaza and Don't "Push" Your Pull Requests by Ilya Grigorik. All code submissions will be rigorously reviewed and tested further by the upgrade-assistant team, and only those that meet an extremely high bar for both quality and design/roadmap appropriateness will be merged into the source.
You will need to sign a Contributor License Agreement when submitting your pull request. To complete the Contributor License Agreement (CLA), you will need to follow the instructions provided by the CLA bot when you send the pull request. This needs to only be done once for any .NET Foundation OSS project.
If you don't know what a pull request is read this article: https://help.github.com/articles/using-pull-requests. Make sure the repository can build and all tests pass. Familiarize yourself with the project workflow and our coding conventions. For general coding guidelines, see here.
Tests in upgrade-assistant follow the following pattern:
- Testing Framework used is XUnit.
- Mocking Framework used is Moq (with AutoMock).
- Data generation Framework used is AutoFixture.
Tests need to be provided for every bug/feature(except docs or samples) that is completed.
Ad-hoc testing of the analyzer/codefixers can be done via src/extensions/default/analyzers/Vsix/Microsoft.DotNet.UpgradeAssistant.Extensions.Default.Vsix.csproj. Set it as start-up and it will launch the experimental instance of Visual Studio with the analyzers/codefixers added as an extension.
Your pull request will now go through extensive checks by the subject matter experts on our team. Please be patient while upgrade-assistant team gets through it. Update your pull request according to feedback until it is approved by one of the upgrade-assistant team members. Once the PR is approved, one of the upgrade-assistant team members will merge your PR into the repo.
The tool may produce long file paths during build, in order to not run into PathTooLongException either change the LongPathsEnabled setting under registry or build upgrade-assistant from a folder location with a shorter path.
More information on DevOps, check this link.