Thank you for your interest in Microsoft Graph documentation!
- Ways to contribute
- Before we can accept your pull request
- Use GitHub, Git, and this repository
- Contribute and edit content
- Contributions from community members
- More resources
You can contribute to Microsoft Graph documentation in these ways:
- Contribute to articles via the public Microsoft Graph developer docs repository.
- Report documentation bugs by scrolling to the Feedback section at the bottom of the related documentation page. You can select This page and create new feedback that will be tracked via GitHub Issues.
- Add or vote for documentation requests at Microsoft Tech Community.
Minor corrections or clarifications you submit for documentation and code examples in this repository don't require a Contribution License Agreement (CLA). Submissions are taken in the form of pull requests. We do our best to review pull requests within 10 business days.
If you submit new or significant changes to documentation and code examples, you need to sign a Contribution License Agreement (CLA) before we can accept your pull request if you are in one of these groups:
- Members of the Microsoft Open Technologies group
- Contributors who don't work for Microsoft
As a community member, you must sign the Contribution License Agreement (CLA) before you can contribute large submissions to this project, but you need to complete and submit the documentation only once. Carefully review the document; you might also need to have your employer sign the document.
Signing the Contribution License Agreement (CLA) doesn't grant you rights to commit to the main repository. However, it does mean that the Microsoft teams will be able to review and consider your contributions and you'll get credit if we do.
You can download or digitally sign the Contribution License Agreement (CLA) here. Once we receive and process your CLA, we'll do our best to review your pull requests within 10 business days.
Note:
- Most of the information in this section can be found in GitHub Help articles. If you're familiar with Git and GitHub, skip to the Contribute and edit content section for the particulars of the code/content flow of this repository.
- Before contributing for the first time to Microsoft Graph docs, employees of Microsoft should complete configuring their GitHub accounts. See the Document section of the internal Microsoft Graph Partners onboarding documentation for details.
- Set up a GitHub account so you can contribute to this project. If you haven't done so already, go to GitHub Home and do it now.
- Set up your machine with Git. Follow the instructions in the Setting up Git Tutorial.
- Create your own fork of this repository. To do this, at the top of the page, select the Fork button.
- Copy your fork to your local machine. To do this, open GitBash. At the command prompt enter:
git clone https://github.com/{your user name}/microsoft-graph-docs.git
Next, create a reference to the root repository by entering these commands:
cd microsoft-graph-docs
git remote add upstream https://github.com/microsoftgraph/microsoft-graph-docs.git
git fetch upstream
Congratulations! You've now set up your repository. You won't need to repeat these steps again.
Follow the guidance for Quick edits to existing documents in our contributor guide.
Limit each branch to a single concept/article to streamline the workflow and reduce the chance of merge conflicts. The following types of contribution are appropriate for a new branch:
- A new article (and associated images)
- Spelling and grammar edits on an article
- Applying a single formatting change across a large set of articles (for example, applying a new copyright footer).
After you raise a PR, a content reviewer will review your pull request and guide you on the next steps. The following are basic guidelines of contributions that are accepted:
- Fix grammar and spelling errors and broken links
- Fix omissions in existing sections
- Correct existing or add new HTTP examples
- Move sections in reference and resource files
- Add code snippets (C#, JavaScript, Go, PowerShell, PHP samples) to examples. These code snippets are autogenerated weekly for new and updated HTTP examples
- Correct existing code snippets (C#, JavaScript, Go, PowerShell, PHP samples)
- Add missing properties or documentation
To recommend changes related to one of the types in this "Don'ts" list, file a docs issue instead.
Community members can add new examples to API docs. A complete example contains the request section, the response section and a few HTML comment blocks. You can use Graph Explorer to test your requests and generate complete response objects for examples.
The following section shows the structure of a complete example. Line numbers are included for eligibility only.
1: ### Example 1: Get all users
2:
3: #### Request
4:
5: The following example shows a request.
6:
7: <!-- {
8: "blockType": "request",
9: "name": "get_users"
10: } -->
11: ```http
12: GET https://graph.microsoft.com/v1.0/users
13: ```
14:
15: #### Response
16:
17: The following example shows the response.
18:
19: >**Note:** The response object shown here might be shortened for readability.
20:
21: <!-- {
22: "blockType": "response",
23: "truncated": true,
24: "@odata.type": "microsoft.graph.user",
25: "isCollection": true
26: } -->
27: ```http
28: HTTP/1.1 200 OK
29: Content-type: application/json
30:
31: {
32: "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users",
33: "value": [
34: {
35: "displayName": "Conf Room Adams",
36: "mail": "[email protected]",
37: "mobilePhone": null,
38: "officeLocation": null,
39: "preferredLanguage": null,
40: "surname": null,
41: "userPrincipalName": "[email protected]",
42: "id": "6ea91a8d-e32e-41a1-b7bd-d2d185eed0e0"
43: }
44: ]
45: }
46: ```
- Line 1: Add a descriptive title. Start with a verb. Don't skip heading levels.
- Line 3: Add the "Request" header.
- Line 8: Set the blockType to
request
to ensure the example is validated and code samples are autogenerated a few days after the PR is published. - Line 9: Set a unique name for the example that doesn't conflict with names used by other examples. This name will be used for the code sample files.
- Lines 10-13: Add your request URL inside an HTTP code block. Using
msgraph-interactive
instead ofhttp
allows developers to use the "Try-It" button in docs. - Line 15: Add the "Response" header using the same header level as the "Request" header.
- Line 17: Add any explanation for the example response.
- Lines 21-26: Indicate details about the type of response object that's returned. See other examples in the same document for guidance.
- Lines 27-46: Add the response object in an HTTP code block.
- Microsoft Learn documentation contributor guide overview
- For more information about Markdown, go to their site.
- For more information about using Git and GitHub, first check out the GitHub Help and if necessary contact the site administrators.