Contributing Guidelines
Thank you for your interest in contributing to the SharePoint Framework Toolkit extension. In this guide, we will walk you through the steps to get started.
π Before you start
Section titled βπ Before you startβIn order to help us process your contributions, please make sure you do the following:
- Donβt surprise us with big PRs. Instead, create an issue and start a discussion so we can agree on a direction before you invest a large amount of time.
- Create your branch from
dev
(NOTmain
). This will make it easier for us to merge your changes. - Submit your PR to the
dev
branch of this repo (NOTmain
). PRs submitted to other branches will be declined. - Let us know whatβs in the PR: sometimes code is not enough and in order to help us understand your awesome work please follow the PR template to provide required information.
- Donβt commit code you didnβt write. Sure, Copilot may help π.
Donβt be afraid to ask questions. We are here to help you succeed in making this a better product together.
π£ How to start - Minimal path to awesome
Section titled βπ£ How to start - Minimal path to awesomeββ οΈ Important: Before you start, note that this product uses the CLI for Microsoft 365 under the hood. Currently, VS Code extensions do not support ECMAScript Modules (ESM), and starting from version 7.x, the CLI has been refactored to use ESM. To overcome this, we are using a fork of CLI that is still maintained in CommonJS (CJS). You can find it in the following Github repo/branch cli-cjs.
- Fork this project. When creating the fork, deselect the checkbox βCopy the
main
branch onlyβ to get bothmain
anddev
branches. - Clone the forked repository.
- In the cloned repository, run the npm install command:
npm install
. Please note that the recommended node version is 18.17.X or higher. - Clone the CJS version of CLI for Microsoft 365 from the following Github repo/branch cli-cjs
- In the cloned CLI for Microsoft 365 repository, run:
npm install
,npm run clean
,npm run build
to generate the CLI for Microsoft 365 output. Make sure the cloned CLI for Microsoft 365 repository is in the same workspace as the SharePoint Framework Toolkit repository. For example, your folder structure should look like this:
root: - cli-microsoft365 - vscode-viva
- From the cloned fork of the SharePoint Framework Toolkit repository, navigate to the
scripts
folder and run the script cli-for-microsoft365-copy-local-version, passing theworkspacePath
(full path to the root folder of your workspace). This script will copy the output of the CLI for Microsoft 365 to the SharePoint Framework Toolkit extensionβsnode_modules
folder. - Open the SharePoint Framework Toolkit project in Visual Studio Code.
- Run the watch command:
npm run watch
. - Press
F5
to start debugging the extension.
β οΈ Important: When debugging the SharePoint Framework Toolkit extension in the context of an SPFx project, you may notice errors in the debug console if the following folders are missing:
.\.vscode\tours
and.\.github\tours
. These errors are caused by theCodeTour
extension, a dependency of the SPFx Toolkit, and they do not affect the functionality of the SPFx Toolkit extension. To suppress these errors during debugging, you can create empty.tours
folders in your project. Alternatively, you can safely ignore these errors as they do not impact the extensionβs behavior.
π Repository branches
Section titled βπ Repository branchesβYou may have already noticed that this repo maintains two branches: main
and dev
. Whatβs even more important is that every feature branch should be created based on dev
branch and Pull Requests should target dev
branch not main
. Itβs important to understand why the meaning and purpose of each branch:
main
- based on this branch new major and minor releases are created. Only critical bug fixes or feature updates go directly to this branch. All others should first be merged todev
branch and then merged to fromdev
tomain
with a separate PR. This branch is main repository branch and keeping clean change history is important.dev
- based on this branch pre-releases are created. Every change should be merged to this branch first with a PR before they get merged tomain
branch. During the release flow, this branch may be rebased and force pushed againstmain
branch, so it may be recreated based on the currentmain
branch state.
π§ͺ Tests
Section titled βπ§ͺ TestsβTo run tests in debug mode:
- install extension https://marketplace.visualstudio.com/items?itemName=ms-vscode.extension-test-runner
- run
npm run package && npm run compile-tests
- run
Extension Tests
in debug
To run:
- run
npm run package && npm run compile-tests
- run
npm run test
and check the result in terminal
π Documentation
Section titled βπ DocumentationβSPFx Toolkit documentation is built using Astro Starlight and hosted at https://pnp.github.io/vscode-viva
When you open a PR, make sure the relevant documentation is updated as well.
All documentation pages are written in MDX format (.mdx
) and located in the /docs
folder. Hereβs an overview of the folder structure:
docs/βββ assets/ # Images and other static assetsβββ public/ # Public assets accessible via URLβββ src/β βββ components/ # Astro componentsβ βββ content/β β βββ docs/ # All documentation pages (.mdx files)β β βββ about/ # About pages (changelog, team, etc.)β β βββ features/ # Feature pages (setup, sign in, etc.)β β βββ index.mdx # Homepageβ β βββ ...β βββ styles/β βββ docs.css # Custom stylingβββ astro.config.mjs # Astro configuration and sidebar navigation
β οΈ Important: If your page includes screenshots or other static assets, store them under
docs/assets/images/
. This ensures they are not bundled into the VSIX extension package.
π Running Documentation Locally
Section titled βπ Running Documentation LocallyβTo run docs locally and preview your changes:
- run
cd docs
- run
npm install
- run
npm run start
- Open the URL shown in the terminal (usually
http://localhost:4321
). The site reloads automatically when changes are saved.
βοΈ Documentation Writing Guidelines
Section titled ββοΈ Documentation Writing GuidelinesβWhen writing or editing documentation, follow these guidelines:
- Use a friendly but professional tone
- Avoid slang or overly casual language
- Do not use 100% AI-generated content
- Place your file in the correct folder based on its purpose