{"id":32646,"date":"2017-08-04T11:05:30","date_gmt":"2017-08-04T18:05:30","guid":{"rendered":"https:\/\/blog.xamarin.com\/?p=32646"},"modified":"2017-08-04T11:05:30","modified_gmt":"2017-08-04T18:05:30","slug":"beginners-guide-contributing-xamarin-forms","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/xamarin\/beginners-guide-contributing-xamarin-forms\/","title":{"rendered":"A Beginner&#8217;s Guide for Contributing to Xamarin.Forms"},"content":{"rendered":"<p>\t\t\t\tXamarin.Forms has been <a href=\"http:\/\/open.xamarin.com\/\" target=\"_blank\">open source<\/a> for over a year now. In that time, we&#8217;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&#8217;ll outline what kinds of contributions we are looking for and provide a guide to submitting your first bug fix.<\/p>\n<h2>What Contributions Will We Accept<\/h2>\n<p>In short, we&#8217;ll entertain anything that makes the Xamarin.Forms product better in terms of stability, quality, and capability. This may take the shape of:<\/p>\n<ol>\n<li>Bug fixes<\/li>\n<li>Feature implementations<\/li>\n<li>Tests<\/li>\n<li>Readme and Wiki articles or updates<\/li>\n<\/ol>\n<p>Before you start opening Pull Requests on the GitHub project, there are some prerequisites.<\/p>\n<h3>Sign the .NET Foundation Release<\/h3>\n<p>At the time you submit a Pull Request, a <a href=\"https:\/\/dotnetfoundation.org\/\" target=\"_blank\">.NET Foundation<\/a> bot will check to make sure you&#8217;ve signed a Contribution License Agreement. If you haven&#8217;t, you&#8217;ll be prompted to do so. We cannot accept any contributions until this is completed.<\/p>\n<h3>Review the Coding Style Requirements<\/h3>\n<p>We adhere to the <a href=\"https:\/\/github.com\/dotnet\/corefx\/blob\/master\/Documentation\/coding-guidelines\/coding-style.md\" target=\"_blank\">.NET Foundation style guide<\/a> with a few exceptions:<\/p>\n<ul>\n<li>Don&#8217;t use <code>private<\/code> as that&#8217;s the default protection level.<\/li>\n<li>Use hard tabs instead of spaces<\/li>\n<li>Limit lines to a max of 120 characters<\/li>\n<\/ul>\n<p><img decoding=\"async\" class=\"aligncenter size-full wp-image-32699\" src=\"https:\/\/devblogs.microsoft.com\/wp-content\/uploads\/sites\/44\/2019\/03\/Screenshot-2017-08-01-13.45.32.png\" alt=\"\" width=\"2202\" height=\"1372\" \/><\/p>\n<p>For guidance on implementing some of these in your Visual Studio installation, check our <a href=\"https:\/\/github.com\/xamarin\/Xamarin%2EForms#coding-style\" target=\"_blank\">readme<\/a>.<\/p>\n<h2>Let&#8217;s Focus on Bug Fixes<\/h2>\n<p>Have you found a bug and have a fix you want to contribute? Awesome! Before you go too far, do a quick search on <a href=\"https:\/\/bugzilla.xamarin.com\/query.cgi\" target=\"_blank\">Bugzilla<\/a> to see if there are any reports of the same issue. When searching for Xamarin.Forms, choose the Advanced Search option and:<\/p>\n<ul>\n<li><strong>Classification:<\/strong> Xamarin<\/li>\n<li><strong>Product:<\/strong> Xamarin.Forms<\/li>\n<li><strong>Component:<\/strong> None or All to search broadly<\/li>\n<li><strong>Status:<\/strong> All<\/li>\n<\/ul>\n<p>If there is a matching issue and it&#8217;s is marked <strong>In Progress<\/strong>, then someone is already working the issue. If a PR is referenced on the issue, then it&#8217;s likely pending merge on GitHub. When the issue is <strong>Resolved<\/strong> and <strong>Fixed<\/strong>, 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&#8217;ll need to search our <a href=\"https:\/\/developer.xamarin.com\/releases\/xamarin-forms\/\" target=\"_blank\">release notes<\/a>. We have a plan to improve that in the coming weeks.<\/p>\n<p>If there&#8217;s a bug in any other incomplete state, or no bug report at all, then you&#8217;re in luck and ready to proceed!<\/p>\n<h3>Xamarin.Forms Solution Orientation<\/h3>\n<p>As you start exploring the Xamarin.Forms solution, it may seem a by daunting. I&#8217;ll demystify that for you and show you where to focus your attention.<\/p>\n<p><img decoding=\"async\" class=\"aligncenter size-full wp-image-32701\" src=\"https:\/\/devblogs.microsoft.com\/wp-content\/uploads\/sites\/44\/2019\/03\/Screenshot-2017-08-01-13.48.50.png\" alt=\"\" width=\"394\" height=\"568\" \/><\/p>\n<p><strong>Control Gallery\/<\/strong>\nThese 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.<\/p>\n<p><strong>Pages Gallery\/<\/strong>\nAs the name implies, this is another gallery application, but this time for the <a href=\"https:\/\/developer.xamarin.com\/guides\/xamarin-forms\/user-interface\/datapages\/\" target=\"_blank\" rel=\"noopener noreferrer\">DataPages<\/a> implementation.<\/p>\n<p><strong>Platforms\/<\/strong>\nThese projects contain the platform specific implementations of services and most importantly UI controls. When Xamarin.Forms renders a Label on iOS it runs the <a href=\"https:\/\/github.com\/xamarin\/Xamarin%2EForms\/blob\/master\/Xamarin.Forms.Platform.iOS\/Renderers\/LabelRenderer.cs\" target=\"_blank\">Xamarin.Forms.Platform.iOS\/Renderers\/LabelRenderer.cs<\/a>. On Android you&#8217;ll get <a href=\"https:\/\/github.com\/xamarin\/Xamarin%2EForms\/blob\/master\/Xamarin.Forms.Platform.Android\/Renderers\/LabelRenderer.cs\" target=\"_blank\">Xamarin.Forms.Platform.Android\/Renderers\/LabelRenderer.cs<\/a>, or if you&#8217;re using FastRenderers <a href=\"https:\/\/github.com\/xamarin\/Xamarin%2EForms\/blob\/master\/Xamarin.Forms.Platform.Android\/FastRenderers\/LabelRenderer.cs\" target=\"_blank\">Xamarin.Forms.Platform.Android\/FastRenderers\/LabelRenderer.cs<\/a>. When adding controls or fixing controls related bugs, this is where you&#8217;ll effect those changes.<\/p>\n<p><strong>Xamarin.Forms\/<\/strong>\nWhen looking for core implementations of abstract controls, layouts, bindings, triggers, App Links, and other non-platform specific code, search these projects.<\/p>\n<p><strong>Xamarin.Forms.Maps\/ and Xamarin.Forms.Xaml\/<\/strong>\nThese folders are self-explanatory. You probably won&#8217;t spend too much time in those projects unless you happen to really understand those domains.<\/p>\n<h3>Fixing a Bug<\/h3>\n<ul>\n<li><a href=\"https:\/\/help.github.com\/articles\/cloning-a-repository\/\" target=\"_blank\">Clone<\/a> the <a href=\"https:\/\/help.github.com\/articles\/about-pull-requests\/\" target=\"_blank\">Xamarin.Forms code from GitHub<\/a> master branch or <a href=\"https:\/\/help.github.com\/articles\/fetching-a-remote\/#pull\" target=\"_blank\">pull<\/a> to make sure you have the latest.<\/li>\n<li>Create a new <a href=\"https:\/\/git-scm.com\/book\/en\/v2\/Git-Branching-Basic-Branching-and-Merging\" target=\"_blank\">branch<\/a> to host your changes<\/li>\n<li>Open the Xamarin.Forms solution and navigate to the Control Gallery &gt; Xamarin.Forms.Controls.Issues &gt; Xamarin.Forms.Controls.Issues.Shared<\/li>\n<li>Use the <a href=\"https:\/\/github.com\/xamarin\/Xamarin%2EForms\/blob\/master\/Xamarin.Forms.Controls.Issues\/Xamarin.Forms.Controls.Issues.Shared\/_Template.cs\" target=\"_blank\">_Template.cs<\/a> to start a new case following the established naming convention of &#8220;Bugzilla######.cs&#8221; where ###### is the issue id in Bugzilla.<\/li>\n<\/ul>\n<pre class=\"lang:c# decode:true \">using Xamarin.Forms.CustomAttributes;\nusing Xamarin.Forms.Internals;\n\n#if UITEST\nusing Xamarin.UITest;\nusing NUnit.Framework;\n#endif\n\nnamespace Xamarin.Forms.Controls.Issues\n{\n\t[Preserve(AllMembers = true)]\n\t[Issue(IssueTracker.Bugzilla, 1, \"Issue Description\", PlatformAffected.Default)]\n\tpublic class Bugzilla1 : TestContentPage \/\/ or TestMasterDetailPage, etc ...\n\t{\n\t\tprotected override void Init()\n\t\t{\n\t\t\t\/\/ Initialize ui here instead of ctor\n\t\t\tContent = new Label\n\t\t\t{\n\t\t\t\tAutomationId = \"IssuePageLabel\",\n\t\t\t\tText = \"See if I'm here\"\n\t\t\t};\n\t\t}\n\n#if UITEST\n\t\t[Test]\n\t\tpublic void Issue1Test ()\n\t\t{\n\t\t\tRunningApp.Screenshot (\"I am at Issue 1\");\n\t\t\tRunningApp.WaitForElement (q =&gt; q.Marked (\"IssuePageLabel\"));\n\t\t\tRunningApp.Screenshot (\"I see the Label\");\n\t\t}\n#endif\n\t}\n}<\/pre>\n<p>Implement your reproduction case here. If it&#8217;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.<\/p>\n<ul>\n<li>Select a Control Gallery target project to run on simulator or device.<\/li>\n<\/ul>\n<p><img decoding=\"async\" class=\"aligncenter size-full wp-image-32706\" src=\"https:\/\/devblogs.microsoft.com\/wp-content\/uploads\/sites\/44\/2019\/03\/forms-control-gallery.gif\" alt=\"\" width=\"282\" height=\"500\" \/><\/p>\n<p>You should see your repro happening. If not, then it would appear the issue is fixed already.<\/p>\n<ul>\n<li>Implement your fix and retest the repro.<\/li>\n<li>Implement a <a href=\"https:\/\/developer.xamarin.com\/guides\/testcloud\/uitest\/\" target=\"_blank\">UITest<\/a> in the reproduction file. If you&#8217;re not a UITest pro, again reference some of the other fixes in the source. Once you submit the <a href=\"https:\/\/help.github.com\/articles\/about-pull-requests\/\" target=\"_blank\">Pull Request<\/a>, the tests will be run automatically.<\/li>\n<\/ul>\n<p>You&#8217;re now ready to create a <a href=\"https:\/\/help.github.com\/articles\/about-pull-requests\/\" target=\"_blank\">Pull Request<\/a>. 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&#8217;t apply.<\/p>\n<p><img decoding=\"async\" class=\"aligncenter size-full wp-image-32709\" src=\"https:\/\/devblogs.microsoft.com\/wp-content\/uploads\/sites\/44\/2019\/03\/Screenshot-2017-08-01-15.38.36.png\" alt=\"\" width=\"2316\" height=\"1774\" \/><\/p>\n<p><strong>Description<\/strong>\nWhat is the current behavior and what is the expected behavior.<\/p>\n<p><strong>Bugs<\/strong>\nList any and all Bugzilla reports that this applies to<\/p>\n<p><strong>API Changes<\/strong>\nIf 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.<\/p>\n<p><strong>Checklist<\/strong>\nIndicate if you have included tests. If no tests are required or the issue is too difficult to test with a UITest, note that.<\/p>\n<p>And that&#8217;s it. Submit the Pull Request and we&#8217;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&#8217;t take it personally. Speaking for myself, it&#8217;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.<\/p>\n<blockquote style=\"text-align: left;font-size: 16px;padding: 10px 20px;border-left: 3px solid red\"><p>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.<\/p><\/blockquote>\n<p><strong>Adding Features<\/strong>\nBefore you start working on a feature, check out the public <a href=\"https:\/\/forums.xamarin.com\/85747\/xamarin-forms-feature-roadmap\/p1\" target=\"_blank\">Xamarin.Forms Roadmap<\/a> and do a search of the <a href=\"https:\/\/forums.xamarin.com\/\/P1\" target=\"_blank\">Evolution forum<\/a> where we discuss specifications for possible new features and other changes. If you don&#8217;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.<\/p>\n<p>What should you do if you are comfortable implement on one platform, but don&#8217;t know enough to implement the rest of the platforms? Go ahead and open the proposal and invite others to participate.<\/p>\n<p><strong>Tests and Wiki<\/strong>\nAs 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&#8217;s important to test the right things, so if you have any questions please ask.<\/p>\n<p>Our documentation team continues to do amazing work on our <a href=\"https:\/\/developer.xamarin.com\/guides\/xamarin-forms\/\" target=\"_blank\">developer guides<\/a> and the <a href=\"https:\/\/developer.xamarin.com\/api\/root\/Xamarin.Forms\/\" target=\"_blank\">API documentation<\/a>. If you spot any inaccuracies or have suggestions, use the &#8220;I have a problem&#8221; button in the sidebar and send us details.<\/p>\n<p><img decoding=\"async\" class=\"aligncenter size-full wp-image-32710\" src=\"https:\/\/devblogs.microsoft.com\/wp-content\/uploads\/sites\/44\/2019\/03\/Screenshot-2017-08-01-00.00.56.png\" alt=\"\" width=\"540\" height=\"398\" \/><\/p>\n<p>If you have a wiki contribution that doesn&#8217;t quite fit into those documentation categories, let me know and we&#8217;ll consider building up the wiki.<\/p>\n<h2>Happy Contributing!<\/h2>\n<p>I hope you&#8217;ll consider contributing to Xamarin.Forms. There&#8217;s nothing quite like the satisfaction of having your pull request merged and knowing you&#8217;ve just helped out a huge community of amazing developers.<\/p>\n<p>For more information and to get started:<\/p>\n<ul>\n<li><a href=\"http:\/\/open.xamarin.com\/\" target=\"_blank\">open.xamarin.com<\/a> for more guidance on contributing to Xamarin open source<\/li>\n<li><a href=\"https:\/\/github.com\/xamarin\/Xamarin%2EForms\" target=\"_blank\">github.com\/xamarin\/Xamarin.Forms<\/a><\/li>\n<li><a href=\"https:\/\/forums.xamarin.com\/\" target=\"_blank\">Evolution forum<\/a> proposals<\/li>\n<li><a href=\"https:\/\/bugzilla.xamarin.com\/\" target=\"_blank\">Bugzilla<\/a><\/li>\n<\/ul>\n","protected":false},"excerpt":{"rendered":"<p>Xamarin.Forms has been open source for over a year now. In that time, we&#8217;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&#8217;ll outline what kinds of contributions we are looking for and provide a guide to [&hellip;]<\/p>\n","protected":false},"author":553,"featured_media":39167,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[2],"tags":[16],"class_list":["post-32646","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-developers","tag-xamarin-forms"],"acf":[],"blog_post_summary":"<p>Xamarin.Forms has been open source for over a year now. In that time, we&#8217;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&#8217;ll outline what kinds of contributions we are looking for and provide a guide to [&hellip;]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/xamarin\/wp-json\/wp\/v2\/posts\/32646","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/xamarin\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/xamarin\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/xamarin\/wp-json\/wp\/v2\/users\/553"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/xamarin\/wp-json\/wp\/v2\/comments?post=32646"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/xamarin\/wp-json\/wp\/v2\/posts\/32646\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/xamarin\/wp-json\/wp\/v2\/media\/39167"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/xamarin\/wp-json\/wp\/v2\/media?parent=32646"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/xamarin\/wp-json\/wp\/v2\/categories?post=32646"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/xamarin\/wp-json\/wp\/v2\/tags?post=32646"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}