-
Notifications
You must be signed in to change notification settings - Fork 477
Contributing to XamarinCommunityToolkit
!!! This a work in progress !!!
On this page you will find different scenarios that might be true to you depending on who you are or what you want to do. Please find the scenario that seems to describe you or your situation the best and go from there. Are you missing a scenario or is a scenario missing a step? Please open an issue!
- I am a first-time contributor, what should I know?
- I have a great idea for a feature, what do I do?
- I've opened a PR, what can I expect?
- Someone asked me to write a "spec" first? What's that about?
First of all: keep breathing. We'll get through this together. Contributing for the first time to a big(ger) open-source project can be overwhelming, but we're here to help.
That is awesome! We can't wait to see what you have in store for us. Before you go out and work on it, we do like to have a couple of things first. This might seem overhead, but it actually benefits us both. This way, we know what is coming and can anticipate on it and for you it's super helpful to get some early feedback that you can incorporate in your work so you don't work on bits that needs changing anyway. Here is what we would like you to do.
Does the Toolkit already have the feature? Or something similar? What value will your feature add to this? Is there maybe a library out there that is already doing this? Would it be feasible to contact them and see if we can collaborate on that?
1. Open a new feature request issue
Please be as specific and detailed as it makes sense at the time of opening. A good rule of thumb is probably: if it's a bigger feature, include some (pseudo-)code on your plans or planned API. If it's a smaller feature, describe what you want to add and what purpose it would serve.
This stage may take a little longer. Again, depending on the size of the feature we would like to have one or more people approve this feature accordingly.
If it is not already included, we might ask for a spec where you describe the proposed APIs in a technical sense a bit deeper. This is basically where we start shaping the feature to become its best version of itself and you won't get any nasty surprises during the pull request review.
Don't be afraid of some feedback, we still like you very much! We just want to make sure we take in a maintainable API we're happy with. Just see any and all feedback as something to learn from and if something is not clear to you, please ask! We definitely have no idea what we're doing, so we're happy to be proven wrong or simply explain our reasoning.
In some very odd case we might reject the idea and we will explain why
Hooray! Feature approved, let's do this! Now is the time to start working on this and get that PR in. Please make note of our coding guidelines and read up on "I've opened a PR, what can I expect?"
When you opened the PR there is a couple of things going to happen. First, you will be asked to sign a CLA if you haven't already done so. This will happen only if you contribute to the first time.
Additionally, automated builds will start to kick off and check if your code compiles against the rest of the code. You can see the progress and result at the end of your PR page. If there are any errors, click on the details. You will be able to see the build status and the errors. To speed up the process, make sure you fix any errors in there and commit those.
One of the core team, or someone from the community, will come in and review your changes. Now don't worry, we're all friends here. This review is meant to keep the quality high, make the code inline with our guidelines and maybe most of all: you should learn from it!
The review is in no way meant to tell you what you did wrong. In fact, feel free to challenge all the comments on there, just have a good reason to do so. We definitely don't know everything and are open to learn and improve.
A code review is kind of a weird thing. Your PR can still be merged with certain comments left open. Also a lot of comments might be questions for you to think about. It's not all about pointing out what is wrong, some part of it is us trying to figure out how this change fits into our codebase, another part is thinking ahead: how to we see this change evolve from here.
Don't thing that all the comments need a (code) fix. If the intention is not clear, feel free to ask what the commenter means and what action is suggested.
See if the comments make sense, update your code, discuss and repeat until the PR is approved. If you feel the discussion is going nowhere or maybe your priorities in life have changed, please feel free to let us know that you do not wish to continue so we can take it from there and make sure we merge it. You will still get credited for the commits you did earlier.
Celebrate, you did it! Your code is now part of the Xamarin Community Toolkit. When can we expect the next? ;)
We try to respond to your PR and get it merged within a reasonable time. If you feel that we have forgotten about it, feel free to ping someone already involved in the discussion.
A spec is not a very firmly defined thing. Have a look at our spec template for a general idea. A spec is basically a more technically detailed description of your change. Depending on what that change is, you can already outline the API surface (all the public methods and members you're adding), describe some more in text, add screenshots or mocked up images, whatever makes your idea more clear without actually building it.
This way, we can get a better understanding of how you want to implement your idea, without you already putting in all the work with the risk of us not accepting it at the end.
If you have already opened an issue, just edit your initial comment with all the spec details. If you want to propose a feature and you already have some technical details in mind, open an issue with the spec template selected and start filling it in.