A Guide to Contributing to PnP PowerShell
A Guide to Contributing to PnP PowerShell
Contributing to PnP PowerShell is a rewarding journey. Whether you’re a seasoned contributor or a beginner, this guide aims to simplify the process and keep it handy for your next contribution.
Prerequisites
To set up the development to start hacking on PnP PowerShell, install the following
- Install Git
- Install PowerShell 7
- Install Visual Code or Visual Studio Code
- Install .NET SDK 6 (https://dotnet.microsoft.com/download/dotnet/6.0)
Forking and cloning
First things first, make a copy of the repository to start working on your changes. While making minor changes via GitHub’s web editor or Codespaces is an option, I prefer having the repository on my local machine for more flexibility.
Fork Your Repository: This creates your copy of the repository.
Navigate to PnP PowerShell and fork the repository
Clone the Repository
Clone the forked repository onto your local machine using the following commands
# Navigate to the path where the repository will be cloned
cd C:\Users\reshm\source\repos
# Find a nice directory on your filesystem and...
git clone https://github.com/reshmee011/powershell # Clone the repo
cd powershell # Enter the directory
code . # Open the directory in VS Code
Configure upstream
Setting up an upstream allows you to sync changes with the source repository. Create a seperate branch for each feature or issue to work on as it will make easier to create a pull request for the individual feature or issue.
# Configure an upstream so you can sync changes with the source repo
git remote add upstream https://github.com/pnp/powershell
# Create a branch for your issue or feature and check it out
git checkout -b command-xyz
Start hacking
With your environment set up, dive into making your changes!
Explore the Folder structure to grasp the project’s layout.
If a cmdlet is created or updated the corresponding documentation needs to be created or updated to reflect the changes.
Remember, whenever a cmdlet is added or modified, it’s vital to mirror those changes in the documentation. For instance, upon introducing a new cmdlet like Remove-PnPContainer for container deletion, ensure that corresponding .cs and .md files are created or updated to document its functionality.
Debug and Test changes
- Builds a debug version : Use PowerShell 7 or higher to build a debug version for local testing
c:\Users\reshm\source\repos\powershell\build\Build-Debug.ps1
Build debug may fail if PowerShell file is already in use
The resolution is to close any PowerShell code editor loading the PnP.PowerShell.psd1 file including the PowerShell core used to build the file.
- Import the debug version: Import the debug version of PnP PowerShell
import-module "C:\Users\reshm\Documents\PowerShell\Modules\PnP.PowerShell\PnP.PowerShell.psd1"
connect-pnpOnline -Url https://reshmeeauckloo-admin.sharepoint.com -Interactive
$container = get-pnpcontainer -OwningApplicationId a187e399-0c36-4b98-8f04-1edc167a0996
- Add Breakpoints and Debug: Use breakpoints and attach a debugger to pwsh.exe to pause and debug your code.
Run the cmdlet to find out the process id it is running under.
$PID
Running code will code cause it to pause at breakpoints
Commit Changes
Once your changes are ready, run the following cmdlets to commit all changes changing the message to reflect the commit.
# Edit files, add and commit. Then push with the -u (short for --set-upstream) option
git add -A
git commit -m "new cmdlet for remove-pnpcontainer"
git push --set-upstream origin command-xyz
Once above cmdlets are run , you may be prompted to create pull request from the branch created.
Create Pull request
Sync your branch with the main repository and ensure it’s up to date:
To ensure latest before creating a PR
The code below is a set of Git commands used to synchronize your local repository with the main repository before creating a Pull Request (PR). This is an important step to ensure that your changes are based on the most recent version of the project.
# Sync and rebase main branch to get the latest changes
#git fetch upstream, retrieves all the branches and their respective commits from the 'upstream' repository, which is typically the original repository you forked. However, this command doesn't merge any changes into your local branches.
git fetch upstream
#switch to the 'dev' branch
git checkout dev
#pulls the latest changes from the 'dev' branch of the upstream repository and rebases your local 'dev' branch on top of those changes. Rebasing is a way to integrate changes from one branch into another. It moves or combines a sequence of commits to a new base commit.
git pull --rebase upstream dev
# Rebase feature branch to get the latest changes
#switch to feature branch
git checkout command-xyz
#git rebase dev is used to rebase your feature branch onto the 'dev' branch. This means that the changes in your feature branch are applied on top of the changes in the 'dev' branch, ensuring that your feature branch is up-to-date with the latest changes in the 'dev' branch.
git rebase dev
#push all local changes back onto the origin
#Modifies the most recent commit with any staged changes and/or updates the commit message. In this case, --no-edit is used to keep the existing commit message.
git commit --amend --no-edit
#This command updates your current branch with any new changes from the remote repository.
git pull
# This command pushes all local changes in your current branch to the remote repository.
git push
After running these commands, you can navigate to the branch on your browser and create a pull request. This pull request should reference your feature branch and the main(dev) branch of the central repository.
Squash Multiple Commits
You may have more than 1 commit ahead of the upstream repository and it is a good idea to squash multiple commits into one for a cleaner history:
Git rebase
# -i stands for 'interactive rebase'. HEAD~n is a reference to the 'n-th' commit before the current commit (HEAD). For example, if 'n' is 3, this command will let you modify the last three commits.
git rebase -i HEAD~n
Interactive rebasing allows you to modify commits as they are moved to the new base commit. This is particularly useful when you want to clean up a series of commits before merging them into a main branch.
Git opens a text editor with a list of the last ’n’ commits, each on a separate line, and some commands for how to handle each commit. You can change these commands to tell Git what to do with each commit. For example, you can squash commits (combine them), reorder them, modify the commit messages, or even delete them.
After you save and close the file. Please note the command to save and close depends on the tool the text editor was opened. In my scenerio using git via the terminal from visual studio code opened the editor in vim.
*** How to Exit Vim ***
- Press ESC once (sometimes twice)
- Type :q and press Enter/return if no changes
- Type :wq and press Enter/return to keep changes
- Type :q! and press Enter/return to discard any changes made.
Git will apply the changes you’ve specified. View post Git Tools - Rewriting History for more details.
This can help you create a clean, understandable commit history. Once ready, create the pull request via the GitHub site and fill in the details.
Git reset
An alternative to rebase is to use git reset soft, view difference between git reset hard and git reset soft for more details.
git reset --soft HEAD~7
git add -A
git commit -m "new message"
git pull
git push
Outcome of above command
After the rebase or reset, push the changes to the remote repository with the git push command.
git push –force-with-lease
The –force-with-lease flag confirms whether the remote branch matches the version of the one you are merging. It ensures that any new commits pushed in the interim are acknowledged and rejects the push if the remote branch has been modified in between.
Create Pull Request by clicking the button Create Pull Request
Fill in details
Remove a file from a Git Pull Request
In case the Pull Request has unnecessary changes to unintented files, e.g. pnpframework_hash.txt or version.txt, use git checkout to get exact file from the remote repository.
git checkout origin/dev pnpframework_hash.txt
git checkout origin/dev version.txt
git commit --amend --no-edit
git push -f
Troubleshooting
Should any issues arise during the pull request process, inspect the PR checks for detailed feedback. If needed, resolve conflicts or errors encountered.
Drilling on the failed step by clicking on details may reveal the issue why it failed. In that instance there were no issues with the Pull Request submitted but was due to a new version being released. Reach out to any of the PnP PowerShell Maintainers : Gautam Sheth, Veronique Lengelle or Koen Zomers to understand if you may need to amend anything in your codebase to ensure a successful build.
You may delete the repository after the PR is merged and recreated the fork each time you need to contribute to ensure latest.
Final Touches
Once you have made minor changes to a repository, you are ready to amend your commit. You can do this by using the –no-edit flag:
git add -A
git commit --amend --no-edit
git pull
git push
Please check Getting Started with Git for helpful git cmdlets you may use.
Conclusion
Contributing to PnP PowerShell is a learning process. Remember, each contribution counts, and this guide is your roadmap to make impactful changes seamlessly. Happy coding!
References
Contributing as a holiday season present
GitHub Universe Cloud Skills Challenge
What Are Squash Commits in Git: A How-To Guide for 2024