Getting Started: Contribute

Thank you for your interest in contributing to the PnP JS Core library. Everyone is welcome to contribute and both large and small contributions are appreciated! Below are a few points to keep in mind when you are getting ready to begin to help ensure we can process your pull requests quickly. You can also follow the guide to setup your development environment. We look forward to working with you!

Contribution Guidelines

• Target your pull requests to the dev branch
• Include a test for any new functionality and ensure all existing tests are passing by running gulp test
• Ensure tslint checks pass by typing gulp lint
• Keep your PRs as simple as possible and describe the changes to help the reviewer understand your work
• If you have an idea for a larger change to the library please let us know and let's discuss before you invest many hours using either Gitter or create an issue - these are very welcome but want to ensure it is something we can merge before you spend the time :)
• We have integrated bithound into the PR process - you can safely ignore any failed checks for now, these will NOT prevent your PR from being accepted.

Setup your Environment

These steps will help you get your environment setup for contributing to the core library.

1. Install Visual Studio Code - this is the development environment we will use. It is similar to a light-weight Visual Studio designed for each editing of client file types such as .ts and .js. (Note that if you prefer you can use Visual Studio).

2. Install Node JS - this provides two key capabilities; the first is the nodejs server which will act as our development server (think iisexpress), the second is npm a package manager (think nuget).

3. On Windows: Install Python v2.7.10 - this is used by some of the plug-ins and build tools inside Node JS - (Python v3.x.x is not supported by those modules). If Visual Studio is not installed on the client in addition to this C++ runtime is required. Please see node-gyp Readme

4. Install a console emulator of your choice, for Windows Cmder is popular. If installing Cmder choosing the full option will allow you to use git for windows. Whatever option you choose we will refer in the rest of the guide to "console" as the thing you installed in this step.

5. Install the tslint extension in VS Code:

   1. Press Shift + Ctrl + "p" to open the command panel
   2. Begin typing "install extension" and select the command when it appears in view
   3. Begin typing "tslint" and select the package when it appears in view
   4. Restart Code after installation

6. Install the gulp command line globally by typing the following code in your console npm install -g gulp-cli

7. Now we need to fork and clone the git repository. This can be done using your console (command: git clone https://github.com/OfficeDev/PnP-JS-Core.git) or using your preferred Git GUI tool.

8. Once you have the code locally, navigate to the root of the project in your console. Type the following command:

• npm install - installs all of the npm package dependencies (may take awhile the first time)

9. Copy settings.example.js in the root of your project to settings.js. Edit settings.js to reflect your personal environment (usename, password, siteUrl, etc.).

10. Type gulp serve and you should see the browser launch and a random string of length 5 will be displayed on the page. Also, you can copy the markup shown into a script editor web part in your test SharePoint site. Then use scratchpad.js locally to test/explore the API. You can un-comment any of the existing lines, or add your own. Save scratchpad.js and refresh your browser and you can see your changes (provided you use one of the supplied "show" methods). Be sure to keep gulp serve running locally so your changes can be read. Also note, you may have to allow unsafe scripts since you are serving from localhost to run the scratchpad.

Because we are watching the files, any changes will be reflected in the served files after a new build is complete. You can point from a script tag in your SharePoint site to the http://localhost:3000 site to use the files. Any changes you make will be reflected thanks to the watched build.