Improve contributor onboarding experience/docs

[jfversluis]

I would love to improve the contributor onboarding experiencing. Which probably has a lot to do with having a good "getting starting" documentation on everything you want to know.

The thing that is not clear to me is where first-time contributors would go and look. Is the contributing.md the first thing people will go look for? Will you start on the wiki? What could help to make you clear where to start?

Besides from establishing the right location, we should also think about content. Things I would say that are important:

• Prerequisites
  • What do I need on my machine
• How to fork/clone/get the code
  • Good practices, i.e.: create a branch, do a rebase and how
  • How to update your repo from upstream
• How to run
• Solution/project structure
  • A lot will be going through it and gaining experience, but at least high overview, i.e.: where to find renderers, control gallery and noting that the naming of the renderers isn't always consistent etc.
• Process of doing a feature/change
  • Check or open issue first, wait for some validation/confirmation
  • Do work and open PR
    • Find build output
• How to interact with team

What else should be in there that is important for you to know before you start?

If we want to get all of this in a contributing guide, I circle back to location. To structure all of this the wiki would probably be a better option. Of course it's not a zero sum decision; the contributing.md could also be a summary and pointing to different other resources.

When the wiki is indeed being used; how easy is it to port that to .NET MAUI? Besides just copy/pasting everything.

Every and any insight is much appreciated!

[jfversluis]

From here by @EmilAlipiev

Hi @jfversluis

I think that should be on the official Microsoft docs where we check documentation for all about xamarin.forms.
For me there are 2 big challenges on contributing xamarin.forms.

1. Fork vs Clone; It is tedious to work with a fork if you want to send PR. First i started with fork and you need to create branch on your fork and probably merge in your master fork to test if you have multiple fork branches to see if they are working all together. Then you should PR for each. I understand that you cannot allow everyone to work on a clone and PR directly. Like james mention's here https://youtu.be/TSi9cFRFuN4?t=398 this confusion occurs every time for us. Video is good indeed, i wish it was done long time ago.
2. Source code has no single comment to explain what is what. For example, i have been reverse engineering CollectionView recently and it is complicated structure from CollectionViewRenderer->GroupableItemsViewRenderer->SelectableItemsViewRenderer->StructuredItemsViewRenderer->ItemsViewRenderer->ViewRenderer->VisualElementRenderer and finally inherits native Panel element of UWP.
   I wish there was comments explaining each those renderers. People would waste less time and you would know that on which renderers OnElementPropertyChanged you should implement when Item is changed or entire layout is changed etc.

[jfversluis]

Thank you for sharing this! I'll address them using the same numbering.

1. I see why that might be a think to get used to. It's a bit more work, but like you said; it's impossible to give everyone on GitHub right on every repository to do contributions. I'm afraid this is just something that is a fact of life. However, when you learn more and more about git, you'll discover that it is pretty powerful and switching your changes that you might have incidentally created on a clone, can easily be shifted to a fork and then do a PR from there. Would you be interested in some content around git as a concept then? I'm sure there is a lot of that already, but maybe specific to this kind of OSS contributing.

2. Hm gotcha. So, the thing is, Forms is a quite mature and big framework. When I joined the time I had spent some time working on it, but I still had to find my way around some things. Of course, we want to make it as easy as possible, but I think there will always be some kind of learning curve to be expected. I'm not sure it adding comments to everything in code will make that better. It will make all the code just bigger and readability will go down.
   I think the renderers docs are already pretty good. They may not go into detail about every specific renderer, but I feel they give a nice overview of what is there and how to work with them. Did you see these docs? What is missing from them according to you?

[bmacombe]

I just got done digging through the UWP CollectionView renderer, it does take a few hours of looking at it to get a feel for it. The best suggestion I have for digging into any of the platform code is to set a breakpoint at an entry point and start hitting F10/F11 for a while. I've personally gone from terrified of the platform and core code to submitting PRs for it. @jfversluis and the rest of the team are always very nice and very helpful even when you break things! I've learned so much more about how XF works under the hood and it's very helpful in my own projects.

[domagojmedo]

I don't usually have windows workflow installed on the machine and first time visual studio prompts me to install additional workflows, but even after that building the solution fails and I just unload all the windows projects. Maybe it would be possible to add what projects to unload so the solution builds without the windows part?
I'm guessing most of the people are interested in iOS/Android part for mobile apps.

[bmacombe]

Are you sure you have the UWP 16299 SDK installed?

[bmacombe]

also you will get those errors on iOS...you can ignore them

[domagojmedo]

Are you sure you have the UWP 16299 SDK installed?

How can I verify that?

[bmacombe]

Open the VS installer, modify your current install and look at the Individual Components tab

[domagojmedo]

It's not (I'll install it later just to have all required components), but I don't need UWP TBH, so I just unloaded it. In the end I had to unload

1. Xamarin.Forms.ControlGallery.Android
2. Xamarin.Forms.Platform.Android.UnitTests
3. Xamarin.Forms.Platform.UAP.UnitTests
4. Xamarin.Forms.Core.iOS.UITests

and after that I was able to build the solution

[EmilAlipiev]

Project is also pretty large. When I open the project. this is what i see in my task manager. We need to get rid off or archive old test cases and clean other unnecessary stuffs.

[jfversluis]

While there probably could be some cleaning up, I don't think there is a lot of old test cases that we can actually clean up. But I guess there could be some solution files for different target platforms and just focussing on the core Forms bits. Would that help in your opinion?

I.e.: have a solution that only has Android and UWP ControlGallery and the bits that support that.

Would you also be able to look at my questions/remarks here: #11320 (reply in thread)

[EmilAlipiev]

can we create another shared project and pump all the all bugzilla test cases into that and excluded from solution? There will be still in the source code when you clone and fork it but they wont be loaded into the solution and if anyone needs them simply can reattach it and reuse it.

[programmation]

Several issues:

• XF is quite a large project. This is its own barrier to entry since there’s such a large amount to learn in order to operate it correctly.
• Most adjustments also need to supply Unit Tests and/or UI Tests to validate the new code. This is something that many people do not know how to do.
• Multiple platforms. Most people I’ve seen are good at one platform and OK at another but probably couldn’t cover all of the supported platforms of XF.
• Multiple platforms. Coding for all platforms requires a mix of hardware and software that many people will not be able to access. VS Mac can’t do UWP projects; VS Win can’t do MacOS projects; and then there’s Tizen / tvOS.
• Need to master a complex workflow in order to contribute (fork + rebase + PR to original repo). This would get easier the more a person does it, but the first time might require quite a bit of hand-holding.
• Code style. PRs get rejected and have to be re-done for not following style.

How about a magic shell/PowerShell script that

• Creates a fork
• Creates a branch in the fork
• Checks out the code
• Creates new test case / UI Test case

And another pre-PR script that

• Applies coding style
• Rebases on main
• Pushes to the forked repo
• Creates the PR against XF

GitHub could do most of this itself. It would also make a pretty impressive enhancement to any IDE.

[jfversluis]

Thank you so much for this amazing reply! This holds a lot of valuable stuff. And I like the automation bits. Not sure at this point how feasible that is, but sure something to think about. Would you happen to know any other repo that might have this or scripts that kind of do the things you mention?

As for the rest, let me lift out some bits.

Multiple platforms. Most people I’ve seen are good at one platform and OK at another but probably couldn’t cover all of the supported platforms of XF.

Most certainly true. How would you picture a solution for this? I mean, PRs are already open for a good amount of time now, if we were to allow people to do just 1 platform and have someone else come in to do the other, that would probably make that even worse.

Or would you like to see the team then pick up the remaining platforms? I think they are very willing, but not always able. The power of the community contributions is that issues get solved that do not always have the main focus of the team. Creating a PR that fixes 1 platform and then waiting for the team to pick up the rest might induce that same waiting time because the issue might just not be in scope atm.

Again, I want to emphasize that this is not because they are not willing, it's just that priorities do not always line up the same way.

Multiple platforms. Coding for all platforms requires a mix of hardware and software that many people will not be able to access. VS Mac can’t do UWP projects; VS Win can’t do MacOS projects; and then there’s Tizen / tvOS.

I hear what you're saying but IMO this is only true to some extend. People that are going to contribute here will almost always be mobile developers, else it will make little sense to contribute something here I guess. Because of that, there is a good chance that said people have at least Android and iOS hardware available. Or at the very least access to emulator/simulators of those platforms.

Or course the team understands that this is not true for everyone and is more than willing to run it on a certain platform to test things out and implement it for a certain platform wherever possible.

Tizen and tvOS is not really a focus right now, the three primary platforms would be Android, iOS and UWP. I think with .NET MAUI that is extended a bit to macOS and WPF. So the team does not reject your PR if not all platforms are supported.

The Tizen team does a great job of implementing new features and issues as soon as they are merged and also have great support with emulators on both Windows and macOS so if it's something that the contributor is willing to look into, it's certainly not impossible to do.

Need to master a complex workflow in order to contribute (fork + rebase + PR to original repo). This would get easier the more a person does it, but the first time might require quite a bit of hand-holding.

That can definitely be a bit daunting. I've been there. What would the hand-holding look like? Better docs? Being able to have a red Bat-phone that you can call to for help? I'm very happy to help anyone and everyone go through their first PR, in fact I did just that. But I feel the content that we created around that is too hard to discover or there is still something missing. So I'm happy to discover what that is so that can be worked on.

Code style. PRs get rejected and have to be re-done for not following style.
Is this based on a real-life experience?

I don't feel that PRs are rejected in general; all and every effort is appreciated, there might be some feedback to be worked on, but I think it's very rare that a PR really doesn't pass the bar.

And having that said; I don't feel that "just" style is a reason to reject any PR. I'm curious to hear more about where this comment comes from :)

Again, thank you for this great feedback! Very helpful!

[programmation]

Unfortunately I don't have any solution ideas for the multi-platform issues. It's just a given to me that having the expertise to develop for 3+ platforms at once isn't something a person can pick up in 5 minutes. Perhaps there might be a way to team contributors up with others who have platform expertise in areas I don't? For example, I might be able to do the iOS renderer for a control, but struggle with the Android or UWP side. Maybe there are other developers who could take up the slack, but how do I find them and invite them to contribute? Maybe a register of potential helpers with their areas of expertise? How do we solve the need to have multiple forks and/or multiple people accessing the forked feature repos without exposing my other repos to unwanted extra users? Is this already a solved problem? I'm sure that the fork/branch/update/PR cycle must happen so much on GitHub that it could be automated with some behind the scenes magic. I benefit every day from the way the SourceTree app knows how to make a PR on BitBucket. Is there something (VS extension?) that could do the same from VS, that we could tailor to the Xamarin Forms workflow?

I get in and read the XF source almost every day, as it's full of useful insights about how to do things. It's also got some (ahem) interesting ideas that I really wouldn't use in a native app, and it side-steps or ignores completely some useful platform features (e.g. the whole RunLoop/AutoLayout mechanism in iOS - where's the usage of SetNeedsLayout or SetNeedsDisplay in the renderers?). If the team is concerned to help users learn XF with a view to being able to contribute to it, I think a focus on installing the project as source code is key to enabling this. It's pretty awkward at the moment to install the XF framework as source, but without doing that it's next to impossible to step through it and learn how it works by observation. Could this be an option in a project template for Visual Studio?

Although it might not seem so, the lack of support for UWP in VS Mac is a serious limitation when thinking about contributing to Xamarin Forms. I'm genuinely puzzled why when something as huge as the editor engine from VS Windows was ported to VS Mac there seems to have been no thought about offering cross-compilation for UWP apps from the Mac as well. I'd be contributing to XF as a hobby/spare time thing, and for people like me it's not an option to purchase enough hardware to do all the platforms.

Regarding code style, perhaps "rejected" was not the right word - I should have said "requested changes". However it's much the same thing since it requires meaningless admin work to do something (e.g. remove private keyword and tidy up spacings) that a half-decent code formatter could do automatically.

While you're listening (thanks!) I think it's also important to highlight that having so many open PRs and outstanding issues in the repo is quite a big barrier in itself. I see the outstanding PR list and think immediately "how on earth is my PR going to get any traction?". So with due respect to the team for the fact that your task is already enormous, I feel strongly that those numbers indicate a few problems the speed of decision-making about PRs in general. I realise the need for care in the process, but it's also completely impractical to have PRs stuck in the workflow for long periods. I'm sorry I don't have a solution for that either, but it definitely makes me think.

[EmilAlipiev]

One other thing i would like to mention. before there were nightly builds, betas etc and i dont see them any longer. I think that something is still happening in nightly builds but not exactly sure what because when i see what was merged daily, it is not much. For example, other day i fixed a crucial bug in CollectionView which blocks me to use it in UWP while i cannot use mouse to scroll it. This is probably priority 1-2 fix because it makes it not usable in Uwp. When should i expect this to be merged? I mean at least nightly or beta would be convenient for such important fixes: But I sent PR to Main. so I guess that it will be merged into Main directly? Shouldnt we have another beta or staging branch to merge first into Beta?

[PureWeen]

At one point we were testing out a direction of having a simplified SLN users can contribute to like this

https://github.com/PureWeen/Xamarin.Forms.Sandbox

Just provide a very targeted "Contributor.sln" where contributors can demonstrate a fix or an API

Remove all the current galleries and just focus it down to the platforms and a MainPage

Even tell users they can just ignore writing any unit tests/UI Tests

If you can just create a MainPage showing it's fixed or the new api works

We'll just shove that into the Gallery :-)

[markmccaigue]

One thing I'd love to be able to do as a new contributor is have a client application running on a device, and step through into the checked-out Forms source code underneath.

Whilst it's possible to make a UI Test in the Forms solution to replicate scenarios, sometimes we see bugs first in our own applications using Forms, and often there are a lot of factors at play in a production app, and so I think this would be a great way for us to easily investigate and move to wards producing a minimal reproduction, which is most likely the first step towards being able to contribute a Forms PR. It's also a very fast feedback way to make experimental changes in the local Forms source and have them run inside your client application.

I feel like this scenario is likely already possible, but despite reaching out a couple of times and following all the documentation I could find, I wasn't able to get this working, or to find a "definitive" guide, and so perhaps this is something that would be useful to include in a contributing section?

Below is a summary of the path I've taken so far using the resources I could find.

I first found this blog post from 2018, https://devblogs.microsoft.com/xamarin/debugging-xamarin-forms/, and I was able to follow it to get a Nuget package built, and have my application consume this Nuget package. This was Visual Studio 2019 on Windows, debugging an Android application on a physical device. However, I was unable to have VS step into the Forms.Init(...), call, instead the IDE stepped over the line. I feel as well like I could be missing a step, as it's not clear to me how the IDE would know where the source files are located, even though the symbols are in the Nuget package.

I then found this document, https://github.com/xamarin/Xamarin.Forms/wiki/How-to-Build-Xamarin.Forms-NuGet, and was able to build another Nuget package using the powershell scripts and Cake, but with the same result as before in the IDE.

I've also been pointed towards SourceLink, https://docs.microsoft.com/en-us/xamarin/xamarin-forms/internals/sourcelink?pivots=windows, but this document mentions that Android is not supported on Windows, whereas Windows seems to be the recommended platform on which to build Forms. I'm also not clear if SourceLink is suitable for local debugging, or if it requires files the source files to be hosted online?

[Elashi]

To be honest I have struggled a lot to be able to contribute. And I hate to see others struggle like I did (and I am still struggling).
I strongly encourage to create a special Discussion Category for beginner contributors. So they can express their struggles and find solutions it.

[jfversluis]

Don't think it's worth it anymore at this time tbh :) with .NET MAUI it has been much easier to contribute from what I heard around me, so better invest there if there is something you want to

[Elashi]

Wow that was a quick reply ! thanks !
I agree. But unfortunately I have an app in production that requires fixes sooner than November 2021
Probably I should fix it locally !

Is it possible to use MAUI for production now ?

Regarding my problems in Xamarin: I have all sorts of problems and I am only developing for Android and iOS. Maybe the reason of my problems is that my app is Right To Left app. Android version of my app has serious bugs on XF 5 but works in XF 4.8 . And my iIOS crashes in XF 4.8 but has problems in XF 5 . So I have to support two branches in my repo, right now, and I keep cherry picking features between them .. Daunting task !

I wish MAUI supports Netsted-CollectionView and RightToLeft better !

[jfversluis]

Sorry to hear that! Even when you get the fix and the PR it might take some time before it's merged and then released. So if you really need anything you might want to take matters into your own hands. By either working around it or worst case, build your own Forms package. But if you do the latter and you get that up and running you might just as well open that PR to Forms and see if they want to merge it! 😄

I wish MAUI supports Netsted-CollectionView and RightToLeft better !

RightToLeft I think has more focus, nested CollectionView, I don't know. I think that has always been recommended against nesting those kinds of controls.

Hope this will help you further, best of luck with you app!