initial contrib guide (#580)

* intial contrib guide

* add paragraph on sync upstream

* add more info on sync upstream

CONTRIBUTING.md

@@ -1,14 +1,40 @@
-# Contributing
+# Contribute to the CoE Starter Kit
 
-This project welcomes contributions and suggestions. Most contributions require you to
-agree to a Contributor License Agreement (CLA) declaring that you have the right to,
-and actually do, grant us the rights to use your contribution. For details, visit
-https://cla.microsoft.com.
+Welcome, and thank you for your interest in contributing to the CoE Starter Kit.
 
-When you submit a pull request, a CLA-bot will automatically determine whether you need
-to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the
-instructions provided by the bot. You will only need to do this once across all repositories using our CLA.
+There are many ways in which you can contribute to the CoE Starter Kit. The goal of this document is to provide a high-level overview of how you can get involved.
 
-This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
-For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/)
-or contact [[email protected]](mailto:[email protected]) with any additional questions or comments.
+## Asking and Answering Questions
+
+Join the [discussions](https://github.com/microsoft/coe-starter-kit/discussions) and ask your question or contribute by answering questions from others. This is a great way to contribute by helping the CoE Starter Kit community
+
+## Report a Bug or submit a Feature Request
+
+Have you found a bug in the CoE Starter Kit or do you want to suggest a new feature? Either way, please let us now by filing an issue while observing the following guidelines
+
+### Look for an existing issue
+
+Before submitting your issue please search the [issues](https://github.com/microsoft/coe-starter-kit/issues) to ensure your issue has not already been reported
+
+If your bug or feature request has already been reported you are welcome to join the conversation by commenting and adding your reaction. Please use reactions to vote and not "+1" comments.
+
+- 👍 - upvote
+- 👎 - downvote
+
+### Submitting your Issue
+
+Select the Issue template that matches the solution for which you want to submit an issue.
+
+File a single issue per problem and feature request. Do not enumerate multiple bugs or feature requests in the same issue.
+
+Do not add your issue as a comment to an existing issue unless it's for the identical input. Many issues look similar, but have different causes.
+
+The more information you can provide, the more likely someone will be successful at reproducing the issue and finding a fix.
+
+Observe the inline guidelines of the Issue template.
+
+## Contribute with Code
+
+If you are interested in contributing to the CoE Starter Kit by fixing issues or adding features please read the [How to Contribute](HOW_TO_CONTRIBUTE.md) guide.
+
+## Thank You

HOW_TO_CONTRIBUTE.md

@@ -0,0 +1,62 @@
+# Contributing
+
+This project welcomes contributions and suggestions. Most contributions require you to
+agree to a Contributor License Agreement (CLA) declaring that you have the right to,
+and actually do, grant us the rights to use your contribution. For details, visit
+[Contributor License Agreement](https://cla.opensource.microsoft.com/).
+
+When you submit a pull request, a CLA-bot will automatically determine whether you need
+to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the
+instructions provided by the bot. You will only need to do this once across all repositories using our CLA.
+
+This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
+For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/)
+or contact [[email protected]](mailto:[email protected]) with any additional questions or comments.
+
+## Branching Strategy
+
+The CoE Starter Kit uses a vnext branch strategy meaning that each solution in the CoE Starter Kit is maintained in a vnext branch, or, next version branch. The vnext branches follows a naming convention that makes it easy to identify the relevant vnext branch for each solution, i.e. the vnext branch for CenterofExcellenceCoreComponents is named CenterofExcellenceCoreComponents.
+
+When creating new releases for the CoE Starter Kit the vnext branches are merged into main, effectively adding next version features and fixes to the latest release.
+
+Following the branching strategy means that **all Pull Requests are made to a vnext branch and never directly to the main branch.**
+
+## Getting your own copy of the source code
+
+Any code (documentation, solution components, yaml pipelines etc.) contribution you want to make to CoE Starter Kit should be made in your own copy of the source code.
+
+> [!NOTE]There are many ways to interact with github depending on your development workflow and the tools and software you use. The steps to create your own copy of the source code will differ depending on your tools and software.
+
+To create a copy of the repository you should fork the CoE Starter Kit repository to your own github account.
+Any contributions you make should be made in your own fork.
+
+> [!NOTE]To learn about GitHub forks visit the GitHub docs: [Working with forks](https://docs.github.com/en/github/collaborating-with-pull-requests/working-with-forks/about-forks)
+
+You should always ensure that your fork is up-to-date with the upstream repository by regularly synchronizing your fork.
+
+The simplest way to synchronize your fork with the upstream repository is via the **Fetch upstream** feature on your fork github page as in below screenshot.
+
+![fetch upstream changes](.attachments/HOW_TO_CONTRIBUTE/fetch-upstream-changes.png)
+
+Selecting **Compare** will allow you to compare the changes in the upstream repository agains your own fork and create a pull request to merge these into your own fork.
+
+Selecting **Fetch and merge** will fetch all upstream changes and merge into your own fork without a pull request work flow.
+
+To manage the synchronization of upstream changes on the command line please refer to the GitHub documentation on [Syncing a fork](https://docs.github.com/en/github/collaborating-with-pull-requests/working-with-forks/syncing-a-fork)
+
+## Local branch strategy
+
+When implementing your contributions in your forked repository it is recommended that you employ a feature branch strategy. This means that you will have a branch for each feature or bug fix that your contribute. This approach helps keep the review process as simple as possible.
+We recommend naming your feature branches in a way that identify the feature or bug fix your are working on by having the issue id in the branch name.
+
+## Pull Requests
+
+When your contribution is complete and you are ready to submit your changes to the CoE Starter Kit repository you should make a Pull Request from your feature branch in your own fork into the relevant vnext branch in the CoE Starter Kit repository.
+
+Before we can accept a pull request from you, you'll need to sign a Contributor License Agreement (CLA). It is an automated process and you only need to do it once.
+To enable us to quickly review and accept your pull requests, always create one pull request per issue and link the issue in the pull request. Never merge multiple requests in one unless they have the same root cause.
+
+## Where to Contribute
+
+To improve the chances to get a pull request merged you should select an issue that is labelled with the help-wanted or bug labels. If the issue you want to work on is not labelled with help-wanted or bug, you can start a conversation with the issue owner asking whether an external contribution will be considered.
+To avoid multiple pull requests resolving the same issue, let others know you are working on it by saying so in a comment.