honeymoose
/
sp-dev-fx-webparts
mirror of https://github.com/pnp/sp-dev-fx-webparts.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Repo documentation updates (#459) 

* markdown fixup, addressed typos

- fixed headings to be H2's (was a bunch of H1's)
- fixed sentence case on page title
- fixed few typos

* remove debug file from root

* fixup github templates

- templates now match same instructions as the sp-dev-docs repo

* updated contrib guide

- fixed typos
- updated style to match simiar style as sp-dev-docs repo
- updated to include detailed steps for submitting PRs
This commit is contained in:
Andrew Connell 2018-04-03 13:07:13 -04:00 committed by Vesa Juvonen
parent a116fffdef
commit f554b902d7
5 changed files with 175 additions and 103 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

160
.github/CONTRIBUTING.md vendored
View File

@ -1,13 +1,15 @@
# Contribution Guidance
If you'd like to contribute to this repository, please read the following guidelines. Contributors are more than welcome to share your learnings with others from centralized location.
## Code of Conduct
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 [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
For more information, see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
## Question or Problem?
Please do not open GitHub issues for general support questions as the GitHub list should be used for feature requests and bug reports. This way we can more easily track actual issues or bugs from the code and keep the general discussion separate from the actual code.
Please do not open GitHub issues for general support questions as the GitHub list should be used for feature requests and bug reports. This way we can more easily track actual issues or bugs from the code and keep the general discussion separate from the actual code.
If you have questions about how to use SharePoint Framework or any of the provided samples, please use the following locations.
@ -15,6 +17,7 @@ If you have questions about how to use SharePoint Framework or any of the provid
* [SharePoint Stack Exchange](http://sharepoint.stackexchange.com/) with 'spfx' tag
## Typos, Issues, Bugs and contributions
Whenever you are submitting any changes to the SharePoint repositories, please follow these recommendations.
* Always fork repository to your own account for applying modifications
@ -22,71 +25,124 @@ Whenever you are submitting any changes to the SharePoint repositories, please f
* If you are submitting multiple samples, please create specific PR for each of them
* If you are submitting typo or documentation fix, you can combine modifications to single PR where suitable
## Submitting changes as pull requests
## Sample Naming and Structure Guidelines
When you are submitting a new sample, it has to follow up below guidelines
* You will need to have a README file for your contribution, which is based on [provided template](../samples/README-template.md) under the Samples folder. Please copy this template and update accordingly. README has to be named as README.md with capital letters.
* You will need to have a picture of the web part in practice in the README file ("pics or it didn't happen"). Preview image must be located in /assets/ folder in the root your you solution.
* README template contains specific tracking image as a final entry in the page with img tag by default to https://telemetry.sharepointpnp.com/sp-dev-fx-webparts/samples/readme-template. This is transparent image, which is used to track popularity of individual samples in GitHub.
* Updated the image src element according with repository name and folder information. If your sample is for example in samples folder and named as react-todo, src element should be updated as https://telemetry.sharepointpnp.com/sp-dev-fx-webparts/samples/react-todo
* If you find already similar kind of sample from the existing samples, we would appreciate you to rather extend existing one, than submitting a new similar sample
* If you for example use Office Graph with React, please rather add new web part to already existing solution, rather than introducing completely new solution
* When you update existing samples, please update also README accordingly with information on provided changes and with your author details
* When you are submitting new sample solution, please name the sample solution folder accordingly
* Folder should start by identifying JS library used - like "react-", "angular-", "knockout-"
* If you are not using any specific JS library, please use "js-" as the prefix for your sample
* Do not use words "sample", "webpart" or "wb" in the folder or sample name - these are samples for client-side web parts repository
* If your solution is demonstrating multiple technologies, please use functional terms as the name for the solution folder
* Do not use period/dot in the folder name of the provided sample
## Submitting Pull Requests
Here's a high level process for submitting new samples or updates to existing ones.
1. Sign the Contributor License Agreement (see below)
2. Fork the main repository to your GitHub account
3. Create a new branch for your fork for the contribution based on dev branch
4. Include your changes to your branch
5. Commit your changes using descriptive commit message - These are used to track changes on the repositories for monthly communications, see [May 2017](https://dev.office.com/blogs/PnP-May-2017-Release) as an example
6. Create a pull request in your own fork and target 'dev' branch
7. Fill up the provided PR template with the requested details
1. Fork this repository [SharePoint/sp-dev-fx-webparts](https://github.com/SharePoint/sp-dev-fx-webparts) to your GitHub account
1. Create a new branch off the `master` branch for your fork for the contribution
1. Include your changes to your branch
1. Commit your changes using descriptive commit message * These are used to track changes on the repositories for monthly communications
1. Create a pull request in your own fork and target `dev` branch
1. Fill up the provided PR template with the requested details
> note. Delete the feature specific branch only AFTER your pull request has been processed.
Before you submit your pull request consider the following guidelines:
## Sample naming and structure guidelines
When you are submitting a new sample, it has to follow up below guidelines
* Search [GitHub](https://github.com/SharePoint/sp-dev-fx-webparts/pulls) for an open or closed Pull Request
that relates to your submission. You don't want to duplicate effort.
* Make sure you have a link in your local cloned fork to the [SharePoint/sp-dev-fx-webparts](https://github.com/SharePoint/sp-dev-fx-webparts):
- You will need to have a README file for your contribution, which is based on [provided template](../samples/README-template.md) under the Samples folder. Please copy this template and update accordingly. README has to be named as README.md with capital letters.
- You will need to have a picture of the web part in practice in the README file ("pics or it didn't happen"). Preview image must be located in /assets/ folder in the root your you solution.
- README template contains specific tracking image as a final entry in the page with img tag by default to https://telemetry.sharepointpnp.com/sp-dev-fx-webparts/samples/readme-template. This is transparent image, which is used to track popularity of individual samples in GitHub.
- Updated the image src element according with repository name and folder information. If your sample is for example in samples folder and named as react-todo, src element should be updated as https://telemetry.sharepointpnp.com/sp-dev-fx-webparts/samples/react-todo
- If you find already similar kind of sample from the existing samples, we would appreciate you to rather extend existing one, than submitting a new similar sample
- If you for example use Office Graph with React, please rather add new web part to already existing solution, rather than introducing completely new solution
- When you update existing samples, please update also README accordingly with information on provided changes and with your author details
- When you are submitting new sample solution, please name the sample solution folder accordingly
- Folder should start by identifying JS library used - like "react-", "angular-", "knockout-"
- If you are not using any specific JS library, please use "js-" as the prefix for your sample
- Do not use words "sample", "webpart" or "wb" in the folder or sample name - these are samples for client-side web parts repository
- If your solution is demonstrating multiple technologies, please use functional terms as the name for the solution folder
- Do not use period/dot in the folder name of the provided sample
```shell
# check if you have a remote pointing to the Microsoft repo:
git remote -v
## Step-by-step on submitting a pull request to this repository
Please see following wiki post from the GitHub repository wiki for exact steps on submitting new pull requests.
# if you see a pair of remotes (fetch & pull) that point to https://github.com/SharePoint/sp-dev-fx-webparts, you're ok... otherwise you need to add one
* How to submit a PR to SharePoint repository? - *Work in progress*
# add a new remote named "upstream" and point to the Microsoft repo
git remote add upstream https://github.com/SharePoint/sp-dev-fx-webparts.git
```
## Merging your existing github projects with this repository
If the sample you wish to contribute is stored in your own Github repository, you can use the following steps to merge it with the Psp-dev-fx-extensions repository:
* Make your changes in a new git branch:
* Fork the sp-dev-fx-extensions repository from GitHub
* Create a local git repository
```
md sp-dev-fx-extensions
cd sp-dev-fx-extensions
git init
```
* Pull your forked copy of sp-dev-fx-extensions into your local repository
```
git remote add origin https://github.com/yourgitaccount/sp-dev-fx-extensions.git
git pull origin dev
```
* Pull your other project from github into the samples folder of your local copy of sp-dev-fx-extensions
```
git subtree add --prefix=samples/projectname https://github.com/yourgitaccount/projectname.git master
```
```shell
git checkout -b react-taxonomypicker master
```
* Ensure your fork is updated and not behind the upstream **sp-dev-fx-webparts** repo. Refer to these resources for more information on syncing your repo:
* [GitHub Help: Syncing a Fork](https://help.github.com/articles/syncing-a-fork/)
* [Keep Your Forked Git Repo Updated with Changes from the Original Upstream Repo](http://www.andrewconnell.com/blog/keep-your-forked-git-repo-updated-with-changes-from-the-original-upstream-repo)
* For a quick cheat sheet:
```shell
# assuming you are in the folder of your locally cloned fork....
git checkout master
# assuming you have a remote named `upstream` pointing official **sp-dev-fx-webparts** repo
git fetch upstream
# update your local master to be a mirror of what's in the main repo
git pull --rebase upstream master
# switch to your branch where you are working, say "react-taxonomypicker"
git checkout react-taxonomypicker
# update your branch to update it's fork point to the current tip of master & put your changes on top of it
git rebase master
```
* Push your branch to GitHub:
```shell
git push origin react-taxonomypicker
```
## Merging your Existing Github Projects with this Repository
If the sample you wish to contribute is stored in your own Github repository, you can use the following steps to merge it with the this repository:
* Fork the `sp-dev-fx-webparts` repository from GitHub
* Create a local git repository
```shell
md sp-dev-fx-webparts
cd sp-dev-fx-webparts
git init
```
* Pull your forked copy of sp-dev-fx-webparts into your local repository
```shell
git remote add origin https://github.com/yourgitaccount/sp-dev-fx-webparts.git
git pull origin dev
```
* Pull your other project from github into the samples folder of your local copy of sp-dev-fx-webparts
```shell
git subtree add --prefix=samples/projectname https://github.com/yourgitaccount/projectname.git master
```
* Push the changes up to your forked repository
```
git push origin dev
```
```shell
git push origin dev
```
## Signing the CLA
Before we can accept your pull requests you will be asked to sign electronically Contributor License Agreement (CLA), which is prerequisite for any contributions to PnP repository. This will be one time process, so for any future contributions you will not be asked to re-sign anything. After the CLA has been signed, our PnP core team members will have a look on your submission for final verification of the submission. Please do not delete your development branch until the submission has been closed.
You can find Microsoft CLA from the following address - https://cla.microsoft.com.
Thank you for your contribution.
Thank you for your contribution.
> Sharing is caring.

58
.github/ISSUE_TEMPLATE.md vendored
View File

@ -1,31 +1,47 @@
#### Important
> Use the following form to submit an issue only if it's related to samples in this repo. If you have an issue related to the SharePoint Framework or its documentation, please submit the issue at [https://github.com/SharePoint/sp-dev-docs/issues/new](https://github.com/SharePoint/sp-dev-docs/issues/new). This will help us respond to your issue faster.
>
> ----
>
> Thank you for reporting an issue or suggesting an enhancement. We appreciate your feedback - to help the team to understand your needs, please complete the below template to ensure we have the necessary details to assist you.
>
> _(DELETE THIS PARAGRAPH AFTER READING)_
Use the following form to submit an issue only if it's related to samples in this repo. If you have an issue related to the SharePoint Framework or its documentation, please submit the issue at [https://github.com/SharePoint/sp-dev-docs/issues/new](https://github.com/SharePoint/sp-dev-docs/issues/new). This will help us respond to your issue faster.
## Category
----
Thank you for reporting an issue or suggesting an enhancement. We appreciate your feedback - to help the team to understand your needs, please complete the below template to ensure we have the necessary details to assist you.
#### Category
- [ ] Question
- [ ] Bug
- [ ] Enhancement
- [x] Enhancement
#### Expected or Desired Behavior
_If you are reporting a bug, please describe the expected behavior. If you are suggesting an enhancement please describe thoroughly the enhancement, how it can be achieved, and expected benefit._
> For the above list, an empty checkbox is [ ] as in <kbd>[</kbd><kbd>SPACE</kbd><kbd>]</kbd>. A checked checkbox is [x] with no space between the brackets. Use the `PREVIEW` tab at the top right to preview the rendering before submitting your issue.
>
> _(DELETE THIS PARAGRAPH AFTER READING)_
#### Observed Behavior
_If you are reporting a bug, please describe the behavior you expected to occur when performing the action. If you are making a suggestion, you can delete this section._
## Expected or Desired Behavior
#### Steps to Reproduce
_If you are reporting a bug please describe the steps to reproduce the bug in sufficient detail to allow testing. Only way to fix things properly, is to have sufficient details to reproduce it. If you are making a suggestion, you can delete this section._
> _If you are reporting a bug, please describe the expected behavior. If you are suggesting an enhancement please describe thoroughly the enhancement, how it can be achieved, and expected benefit._
>
> _(DELETE THIS PARAGRAPH AFTER READING)_
#### Submission Guidelines
_Delete this section after reading_
- All suggestions or bugs are welcome, please let us know what's on your mind.
- If you are reporting an issue around any of the samples, please ensure that you have clear reference on the sample and possibly code file, which should be fixed.
- If you have technical questions about the framework, we’ll be monitoring #spfx, #spfx-webparts, and #spfx-tooling on (SharePoint StackExchange)[http://sharepoint.stackexchange.com/]. You can also alternatively submit your question to (SharePoint Developer group)[https://network.office.com/t5/SharePoint-Developer/bd-p/SharePointDev] at Office Network.
- Remember to include sufficient details and context.
- If you have multiple suggestions or bugs please submit them in separate bugs so we can track resolution.
## Observed Behavior
> _If you are reporting a bug, please describe the behavior you expected to occur when performing the action. If you are making a suggestion, you can delete this section._
>
> _(DELETE THIS PARAGRAPH AFTER READING)_
## Steps to Reproduce
> _If you are reporting a bug please describe the steps to reproduce the bug in sufficient detail to allow testing. Only way to fix things properly, is to have sufficient details to reproduce it. If you are making a suggestion, you can delete this section._
>
> _(DELETE THIS PARAGRAPH AFTER READING)_
## Submission Guidelines
> - All suggestions or bugs are welcome, please let us know what's on your mind.
> - If you are reporting an issue around any of the samples, please ensure that you have clear reference on the sample and possibly code file, which should be fixed.
> - If you have technical questions about the framework, we’ll be monitoring #spfx, #spfx-webparts, and #spfx-tooling on (SharePoint StackExchange)> [http://sharepoint.stackexchange.com/]. You can also alternatively submit your question to (SharePoint Developer group)> [https://network.office.com/t5/SharePoint-Developer/bd-p/SharePointDev] at Office Network.
> - Remember to include sufficient details and context.
> - If you have multiple suggestions or bugs please submit them in separate bugs so we can track resolution.
>
> _(DELETE THIS PARAGRAPH AFTER READING)_
Thanks for your contribution! Sharing is caring.

30
.github/PULL_REQUEST_TEMPLATE.md vendored
View File

@ -1,18 +1,20 @@
| Q | A
| --------------- | ---
| Bug fix? | no - yes?
| New feature? | no - yes?
| New sample? | no - yes?
| Related issues? | fixes #X, partially #Y, mentioned in #Z
| Q | A |
| --------------- | --------------------------------------- |
| Bug fix? | no - yes? |
| New feature? | no - yes? |
| New sample? | no - yes? |
| Related issues? | fixes #X, partially #Y, mentioned in #Z |
#### What's in this Pull Request?
## What's in this Pull Request?
Please describe the changes in this PR. Sample description or details around bugs which are being fixed.
> Please describe the changes in this PR. Sample description or details around bugs which are being fixed.
>
> _(DELETE THIS PARAGRAPH AFTER READING)_
## Guidance
#### Guidance
*You can delete this section when you are submitting the pull request.*
* *Please update this PR information accordingly. We'll use this as part of our release notes in monthly communications.*
* *Please target your PR to 'dev' branch.*
Thanks for your contribution! Sharing is caring.
> *Please update this PR information accordingly. We'll use this as part of our release notes in monthly communications.*
>
> *Please target your PR to `dev` branch. Released documents are in `master` branch.*
>
> _(DELETE THIS PARAGRAPH AFTER READING)_

28
README.md
View File

@ -1,65 +1,65 @@
# SharePoint Framework client-side web part samples & tutorial materials
# SharePoint Framework Client-Side Web Part Samples & Tutorial Materials
This repository contains community samples that demonstrate different usage patterns for the SharePoint Framework client-side web parts.
> We do welcome community contributions to the samples folder in this repository for demonstrating different use cases with SharePoint Framework. Notice that if you use 3rd party libraries, please make sure that library license allowes distributions of it as part of your sample.
> We do welcome community contributions to the samples folder in this repository for demonstrating different use cases with SharePoint Framework. Notice that if you use 3rd party libraries, please make sure that library license allows distributions of it as part of your sample.
SharePoint client-side web parts are controls that appear inside a SharePoint page but run locally in the browser. They're the building blocks of pages that appear on a SharePoint site. You can build client-side web parts using modern script development tools and the SharePoint workbench (a development test surface), and you can deploy your client-side web parts to classic web part pages in Office 365 tenants. In addition to plain JavaScript projects, you can build web parts alongside common scripting frameworks, such as AngularJS and React. For example, you can use React along with components from Office UI Fabric React to quickly create experiences based on the same components used in Office 365
SharePoint client-side web parts are controls that appear inside a SharePoint page but run locally in the browser. They're the building blocks of pages that appear on a SharePoint site. You can build client-side web parts using modern script development tools and the SharePoint workbench (a development test surface), and you can deploy your client-side web parts to classic web part pages in Office 365 tenants. In addition to plain JavaScript projects, you can build web parts alongside common scripting frameworks, such as AngularJS and React. For example, you can use React along with components from Office UI Fabric React to quickly create experiences based on the same components used in Office 365.
# Have issues or questions?
## Have issues or questions?
Please use following logic on submitting your questions or issues to right location to ensure that they are noticed and addressed as soon as possible.
* You have general question or challenge with SPFx - use [sp-dev-docs repository issue list](https://github.com/SharePoint/sp-dev-docs/issues).
* You have issue on specific web part or sample - use [issue list in this repository](https://github.com/SharePoint/sp-dev-fx-webparts/issues).
# Additional resources
## Additional resources
* [Overview of the SharePoint Framework](http://dev.office.com/sharepoint/docs/spfx/sharepoint-framework-overview)
* [SharePoint Framework development tools and libraries](http://dev.office.com/sharepoint/docs/spfx/tools-and-libraries)
* [SharePoint Framework Reference](http://aka.ms/spfx-reference)
* [Visual Studio Extension for SharePoint Framework projects](https://github.com/SharePoint/sp-dev-fx-vs-extension)
# Using the samples
## Using the samples
To build and start using these projects, you'll need to clone and build the projects.
Clone this repository by executing the following command in your console:
```
```shell
git clone https://github.com/SharePoint/sp-dev-fx-webparts.git
```
Navigate to the cloned repository folder which should be the same as the repository name:
```
```shell
cd sp-dev-fx-webparts
```
To access the samples use the following command, where you replace `sample-folder-name` with the name of the sample you want to access.
```
```shell
cd samples
cd sample-folder-name
```
```
and for the tutorials, use the following command:
```
```shell
cd tutorials
```
Now run the following command to install the npm packages:
```
```shell
npm install
```
This will install the required npm packages and dependencies to build and run the client-side project.
Once the npm packages are installed, run the following command to preview your web parts in SharePoint Workbench:
```
```shell
gulp serve
```

2
debug.log
View File

@ -1,2 +0,0 @@
[0206/115652:ERROR:tcp_listen_socket.cc(76)] Could not bind socket to 127.0.0.1:6004
[0206/115652:ERROR:node_debugger.cc(86)] Cannot start debugger server