A Beginner’s Guide for Contributing to Xamarin.Forms
Xamarin.Forms has been open source for over a year now. In that time, we’ve accepted over 700 pull requests and received many more. Have any of those been yours? If not, this is your invitation to participate! In this article, I’ll outline what kinds of contributions we are looking for and provide a guide to submitting your first bug fix.
What Contributions Will We Accept
In short, we’ll entertain anything that makes the Xamarin.Forms product better in terms of stability, quality, and capability. This may take the shape of:
- Bug fixes
- Feature implementations
- Readme and Wiki articles or updates
Before you start opening Pull Requests on the GitHub project, there are some prerequisites.
Sign the .NET Foundation Release
At the time you submit a Pull Request, a .NET Foundation bot will check to make sure you’ve signed a Contribution License Agreement. If you haven’t, you’ll be prompted to do so. We cannot accept any contributions until this is completed.
Review the Coding Style Requirements
We adhere to the .NET Foundation style guide with a few exceptions:
- Don’t use
privateas that’s the default protection level.
- Use hard tabs instead of spaces
- Limit lines to a max of 120 characters
For guidance on implementing some of these in your Visual Studio installation, check our readme.
Let’s Focus on Bug Fixes
Have you found a bug and have a fix you want to contribute? Awesome! Before you go too far, do a quick search on Bugzilla to see if there are any reports of the same issue. When searching for Xamarin.Forms, choose the Advanced Search option and:
- Classification: Xamarin
- Product: Xamarin.Forms
- Component: None or All to search broadly
- Status: All
If there is a matching issue and it’s is marked In Progress, then someone is already working the issue. If a PR is referenced on the issue, then it’s likely pending merge on GitHub. When the issue is Resolved and Fixed, then a Pull Request has been merged to address the issue. Currently, to see if it has been released yet and in which version you’ll need to search our release notes. We have a plan to improve that in the coming weeks.
If there’s a bug in any other incomplete state, or no bug report at all, then you’re in luck and ready to proceed!
Xamarin.Forms Solution Orientation
As you start exploring the Xamarin.Forms solution, it may seem a by daunting. I’ll demystify that for you and show you where to focus your attention.
These projects comprise a gallery application including all of the Xamarin.Forms controls available, and more importantly host bug reproductions with UITests inline. When working on fixing a bug, or just to investigate how a control is expected to work, this bare bones but functional app is where you want to look.
As the name implies, this is another gallery application, but this time for the DataPages implementation.
These projects contain the platform specific implementations of services and most importantly UI controls. When Xamarin.Forms renders a Label on iOS it runs the Xamarin.Forms.Platform.iOS/Renderers/LabelRenderer.cs. On Android you’ll get Xamarin.Forms.Platform.Android/Renderers/LabelRenderer.cs, or if you’re using FastRenderers Xamarin.Forms.Platform.Android/FastRenderers/LabelRenderer.cs. When adding controls or fixing controls related bugs, this is where you’ll effect those changes.
When looking for core implementations of abstract controls, layouts, bindings, triggers, App Links, and other non-platform specific code, search these projects.
Xamarin.Forms.Maps/ and Xamarin.Forms.Xaml/
These folders are self-explanatory. You probably won’t spend too much time in those projects unless you happen to really understand those domains.
Fixing a Bug
- Clone the Xamarin.Forms code from GitHub master branch or pull to make sure you have the latest.
- Create a new branch to host your changes
- Open the Xamarin.Forms solution and navigate to the Control Gallery > Xamarin.Forms.Controls.Issues > Xamarin.Forms.Controls.Issues.Shared
- Use the _Template.cs to start a new case following the established naming convention of “Bugzilla######.cs” where ###### is the issue id in Bugzilla.
[Preserve(AllMembers = true)]
[Issue(IssueTracker.Bugzilla, 1, "Issue Description", PlatformAffected.Default)]
public class Bugzilla1 : TestContentPage // or TestMasterDetailPage, etc ...
protected override void Init()
// Initialize ui here instead of ctor
Content = new Label
AutomationId = "IssuePageLabel",
Text = "See if I'm here"
public void Issue1Test ()
RunningApp.Screenshot ("I am at Issue 1");
RunningApp.WaitForElement (q => q.Marked ("IssuePageLabel"));
RunningApp.Screenshot ("I see the Label");
Implement your reproduction case here. If it’s a more complex case, refer to other issues in this project to find something similar and follow that pattern. In the end you should have a reproduction that demonstrates the problem you are working to solve.
- Select a Control Gallery target project to run on simulator or device.
You should see your repro happening. If not, then it would appear the issue is fixed already.
- Implement your fix and retest the repro.
- Implement a UITest in the reproduction file. If you’re not a UITest pro, again reference some of the other fixes in the source. Once you submit the Pull Request, the tests will be run automatically.
You’re now ready to create a Pull Request. From within your IDE or Git tool of choice, create a Pull Request against the Xamarin.Forms remote on GitHub. This process should take you to the GitHub Pull Request page and populate with the Xamarin.Forms Pull Request template. We ask that you fill out everything you can, and omit anything that doesn’t apply.
What is the current behavior and what is the expected behavior.
List any and all Bugzilla reports that this applies to
If the surface area of any class changed when making this fix, note the changes here. These may indicate breaking or behavioral changes for other users and their legacy applications.
Indicate if you have included tests. If no tests are required or the issue is too difficult to test with a UITest, note that.
And that’s it. Submit the Pull Request and we’ll review it. If there are questions or concerns, the team will submit comments and make requests on code. This review process may feel clinical, so don’t take it personally. Speaking for myself, it’s been a great learning experience to work through the Pull Request process on open source projects, and in nearly every case my contributions have eventually been accepted.
It is also extremely helpful to us and other users if you copy the url to the Pull Request and note it on the referenced Bugzilla issues.
Before you start working on a feature, check out the public Xamarin.Forms Roadmap and do a search of the Evolution forum where we discuss specifications for possible new features and other changes. If you don’t see the feature already covered, open a proposal on the Evolution forum and offer to implement it. The Xamarin.Forms engineering team will review the proposal and provide feedback.
What should you do if you are comfortable implement on one platform, but don’t know enough to implement the rest of the platforms? Go ahead and open the proposal and invite others to participate.
Tests and Wiki
As mentioned, we welcome contributions in these areas as well. We have a several projects for UITests as well as Unit Tests. We have fairly good coverage, but it could always be better. It’s important to test the right things, so if you have any questions please ask.
Our documentation team continues to do amazing work on our developer guides and the API documentation. If you spot any inaccuracies or have suggestions, use the “I have a problem” button in the sidebar and send us details.
If you have a wiki contribution that doesn’t quite fit into those documentation categories, let me know and we’ll consider building up the wiki.
I hope you’ll consider contributing to Xamarin.Forms. There’s nothing quite like the satisfaction of having your pull request merged and knowing you’ve just helped out a huge community of amazing developers.
For more information and to get started: