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

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 (NOT main). This will make it easier for us to merge your changes.
Submit your PR to the dev branch of this repo (NOT main). 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.
If your PR includes new images or screenshots, please compress them using TinyPNG to reduce file size and improve performance.
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

⚠️ 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 both main and dev branches.
Clone the forked repository.
In the cloned repository, run the npm install command: npm install. Please note that the recommended node version is v20 or higher.
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 the CodeTour 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

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 to dev branch and then merged to from dev to main 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 to main branch. During the release flow, this branch may be rebased and force pushed against main branch, so it may be recreated based on the current main branch state.

🚀 Step-by-step contributing guide

Follow these steps to contribute to the SPFx Toolkit extension.

1. Pick an issue

Browse the Issues tab in the main repository and look for issues labeled good first issue or help wanted to work on.

Comment on the issue to let maintainers know you are interested in working on it. In order to prevent multiple contributors from working on the same issue, wait to get assigned to the issue by a maintainer before starting work.

2. Fork, clone, and set up development environment (first-time)

Follow the complete setup process from the “How to start” section above. This includes forking the repository (ensure you get both main and dev branches), cloning your fork, installing dependencies, and verifying everything works with npm run watch and F5 for debugging.

After completing the setup, configure the upstream remote to stay in sync with the main repository:

# Navigate to your cloned repository
cd vscode-viva

# Add the upstream repository as a remote
git remote add upstream https://github.com/pnp/vscode-viva.git

# Verify your remotes
git remote -v

3. Create your feature branch

Create a new branch for your work. Always start from the latest dev branch to minimize potential conflicts:

# Always start from the latest dev branch
git checkout dev
git fetch upstream
git pull --rebase upstream dev

# Create your feature branch (use a meaningful name)
git checkout -b fix-issue-123

Use descriptive branch names that reference the issue number and describe what you are fixing. This makes it easier to track changes across the project.

4. Make your changes

Implement and test your changes thoroughly by running the extension in debug mode (F5) and verifying the functionality works as expected. Also, consider updating documentation in the /docs folder if your changes affect user-facing functionality.

5. Commit and push your changes

Commit your changes with a clear message that explains what was modified and why:

# Stage your changes
git add .

# Commit with a clear message
git commit -m "<commit message>. Closes #123"

# Push your feature branch to your fork
git push origin fix-issue-123

6. Create a pull request

Navigate to your forked repository, create a pull request targeting the dev branch, and fill out the PR template with all relevant details.

Important: Set the base branch to dev, not main. All contributions must go through the dev branch first, unless specifically asked in the issue.

7. Respond to review feedback

Monitor your pull request for comments and review feedback from maintainers. When reviewers request changes, follow the proper workflow to maintain a clean commit history:

First, ensure you have the latest changes and rebase your branch:

# Switch to dev and get latest changes
git checkout dev
git fetch upstream
git pull --rebase upstream dev

# Switch back to your feature branch and rebase
git checkout fix-issue-123
git rebase dev

Next, make the requested changes and amend your existing commits rather than creating new ones:

# Stage the changes
git add .

# Amend the existing commit to keep the history clean
git commit --amend

# Force push updated branch
git push --force-with-lease origin fix-issue-123

🛠️ Recommended tool: GitLens interactive rebase editor

For a better rebasing experience, install the GitLens extension which includes an Interactive Rebase Editor. This tool allows you to:

Easily visualize and configure interactive rebase operations
Drag & drop to reorder commits
Select which commits to edit, squash, or drop through an intuitive UI

Understanding rebasing and when it’s needed

Why Rebasing Becomes Necessary

Rebasing may become necessary when your pull request branch falls behind the latest dev branch. This usually happens if other contributors have modified the same files or nearby code, or if maintainers have merged newer changes into dev after your branch was created. The longer your branch remains open, the higher the chance of such conflicts. Rebasing ensures your branch stays aligned with the latest codebase and prevents merge issues when your pull request is reviewed.

What to Expect from Maintainers

You will usually know a rebase is needed when a maintainer comments on your pull request asking you to rebase your branch with the latest dev. This is simply because new changes have been merged since your branch was created, not because there’s an issue with your work.

Rebase process

When you need to rebase your branch, follow these detailed steps:

# Get latest dev branch
git checkout dev
git fetch upstream
git pull --rebase upstream dev

# Switch back to your feature branch and rebase
git checkout fix-issue-123
git rebase dev

Handling conflicts

During the rebase, you might encounter conflicts:

Automatic Resolution: Git resolves simple conflicts automatically
Manual Resolution: For complex conflicts, open the conflicted files in VS Code, resolve conflicts, stage with git add <filename>, and continue the rebase with git rebase --continue until done.

Troubleshooting rebase issues

If you encounter issues during the rebase process, you can abort the rebase and return to your previous state:

git rebase --abort

If the issue remains, ask maintainers for help.

Pushing after rebase

After rebasing, you will need to force push since the commit history has changed:

# Recommended approach
git push --force-with-lease origin fix-issue-123

# Alternative (use only if you are certain no one else pushed to your branch)
git push --force origin fix-issue-123

🧪 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

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

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

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