Skip to content

Latest commit

 

History

History
152 lines (101 loc) · 5.97 KB

CONTRIBUTING.md

File metadata and controls

152 lines (101 loc) · 5.97 KB
Raw

Contribute to SharePoint developer documentation

These instructions explain how you can prepare your environment to contribute to SharePoint Developer Documentation.

Docs repo structure

Before you decide to contribute, it is important to understand the sp-dev-docs repo structure so you can decide where to add your new doc or update an existing doc.

sp-dev-docs
--assets
--docs
--general-development
--images

The docs folder contains the key developer topics:

docs
--spfx
--apis

At this time, contributions are accepted for:

  • SharePoint Framework
  • SharePoint Webhooks

SPFx Folder

The spfx folder contains documentation for SharePoint Framework. It is further classified into component folders, for example: webparts. This folder will expand with new components as they are released.

docs
--spfx
---web-parts
-----basics
-----get-started
-----guidance

Component folder

Every component folder contains the following folders:

  • basics
    • basics folder contains concept docs that are helpful in building that particular component, for example: web-parts.
  • get-started
    • get-started folder contains walkthroughs and tutorials on how to get started building that particular component, for example: web-parts.
  • guidance
    • guidance folder contains guides, best practices and reference implementations for that particular component, for example: web-parts.

Any images associated with the docs should be uploaded into the sp-dev-docs\images folder.

SharePoint Webhooks

The apis\webhooks folder contains the documentation for SharePoint webhooks. It is further classified into webhook endpoints, for example: lists. This folder will expand with new endpoints as they are released.

docs
--apis
----webhooks
-----lists

webhooks folder contains basic documentation around getting started and any other docs that cover webhooks in general.

webhooks\lists folder contains API documentation around the list subscription service.

Any images associated with the docs should be uploaded into the sp-dev-docs\images folder.

Forking SharePoint Developer Docs repository

The first step is registering yourself on GitHub. Go to https://github.com/ and click on the "Sign up for GitHub" button. Once you're registered ensure you're logged on with your new account and navigate to the Office 365 Developer Patterns and Practices repository at https://github.com/sharepoint/sp-dev-docs. The right top side of the page contains a button called "Fork":

Fork the sp-dev-docs github repository

Clicking on this button will Fork the SharePoint developer documentation repository to your GitHub account. It's actually like taking a copy. Select your personal GitHub account you registered earlier as the account to for this repository.

Once the forking has been done you'll find the docs repo under your account with an URL: https://github.com/YOUR-USERNAME/YOUR-REPOSITORY

Clone the forked repository

Now that you have forked the docs repository, to sync this forked repository to your local machine, you will need to clone the repository. You can find the clone URL in the Clone or download dropdown in the repo page.

Clone the forked SharePoint developer docs repository

If you have any Git Desktop or any git source control installed, you can click the Open in Desktop or follow the steps below:

In the Clone with HTTPs section, click to copy the clone URL for the repository.

  • Open your favorite console terminal.

  • Change the current working directory to the location where you want to clone the docs repository.

  • Type the following command to clone the repository:

git clone https://github.com/YOUR-USERNAME/YOUR-REPOSITORY

Press Enter and your local clone will be created.

git clone https://github.com/YOUR-USERNAME/YOUR-REPOSITORY
Cloning into 'sp-dev-docs'...
remote: Counting objects: 10, done.
remote: Compressing objects: 100% (8/8), done.
remove: Total 10 (delta 1), reused 10 (delta 1)
Unpacking objects: 100% (10/10), done.

Switch to main branch

In order to add your changes, you will need to do those in the main branch.

Type the following command in the console to switch to main branch:

git checkout main

Now, you can update existing docs or add new docs to the docs repo.

Adding new docs

Make sure you upload your doc in the right folders. For instance, web part docs should be in the following folder:

docs\spfx\web-parts

Depending on the doc's intent, you can choose to add your doc into basics or get-started folder.

Submit a pull request

Once you have completed adding your changes, you can submit a pull request.

Navigate to the forked sp-dev-docs repo in your account. Make sure your current branch is main branch.

Once you are in the main branch, you should see a message stating This branch is 1 commit ahead of Sharepoint:main and next to it will be a Pull request link.

Submit a pull request to sp-dev-docs repo

Click the Pull request link to start a new pull request. Make sure you use this template to fill in your changes. Make sure you are creating this pull request against the main branch.

Once you have all the information, click the Create pull request button to submit your pull request.

Create pull request

Syncing your forked repository to keep it up-to-date with the upstream repository

In order to keep your forked sp-dev-docs repo up-to-date with the parent repository, you will need to first configure a remote that points to upstream repository.

Once you have configured the upstream repository, follow the steps here to sync your fork to keep it up-to-date with the upstream repository.