How I Develop Locally With GitHub and Azure DevOps Repos

A peer of mine recently asked about how I manage local code (projects, solutions, Git repos, etc.) that may or may not be synced to a cloud repository (GitHub, Azure DevOps, etc.)  Since I previously blogged about How I Blog – Updated 2018 and I’m a fan of re-using how many keys I have left I thought I would share my personal local development process.

 

Disclaimer

I like to to tell people that “I play a developer on TV”, meaning it has been at least 10 years since I’ve written code as a consultant that was actually deployed to a production system.  Sure I’ve written (or collaborated on) many samples (ex. .Net Core console sample for Microsoft Graph) and proof of concepts for customers these past 10 years, but it wasn’t the primary focus of my job.  So balance everything that I share with what others such as my friend Steve Smith (@Ardalis) share on his Weekly Dev Tips blog and podcast.

 

Local Folder Structure

Currently I develop on Windows so folders and paths will reflect that.  I don’t use the default folder that any of the IDEs or tools below use (generally under my user profile folder such as “c:\Users\[username]\…”).  Instead I create a new folder called Projects at the root of my primary drive (i.e. “c:\Projects”).  Below that folder I then have the following:

  • c:\Projects\_DevOps
  • c:\Projects\_GitHub
  • (All other local-only projects, ex. c:\Projects\localProject1)

Using the underscore for _DevOps and _GitHub means that those folders should be easy to find at the top of this folder structure even if I happen to inadvertently sort the folder.

As for project folders, I’ve thought about subdividing based on topic (ex. SharePoint Online, Azure, Microsoft Graph, etc.) or technology (ex. ASP.NET Core, Blazor, Console, etc.) but since I rarely have a large number of folders I haven’t done anything yet.  I do name my folders and projects based on topic though (ex. BTJ.SPO.ProjectName, BTJ.AZ.ProjectName, BTJ.MG.ProjectName, etc.)  This helps at least group together similar projects.

 

Git / GitHub / Azure DevOps Tools

I use a mix of the following tools to sync my repos and monitor issues or pull requests.

  • Visual Studio Code (VS Code) – VS Code has integrated supported in-box for Git.  I use this for committing and pushing code to my GitHub repositories.
  • Azure Repos Extension for Visual Studio Code – There is an extension for VS Code that adds additional functionality (ex. monitor builds, pull requests, and more) directly into VS Code.

  • GitHub Desktop client – GitHub offers a desktop client that allows you to sync code, create branches, review commit history, and more.  When I’m not directly in VS Code working on a repo I generally use GitHub Desktop.
  • Visual Studio Team Explorer – In general I start most projects in VS Code these days.  For the projects I do work in Visual Studio 2019 (ex. Blazor and some ASP.NET Core) I use the Team Explorer functionality (now available out of the box) to sync repos.  The integration with Azure DevOps and GitHub is good as well.
  • GitHub mobile app – I do submit and review a GitHub issues or pull requests on an infrequent basis.  When I am not at my desk I tend to use the newly released mobile app for GitHub.
  • Browser based pull requests – Some repositories that I collaborate on are very large and not well suited to sync locally (ex. Azure docs, Microsoft Graph docs, etc.)  For these I prefer submitting a pull request directly in the browser.  I previously blogged about this at How to Edit Microsoft Documentation on GitHub.

 

Conclusion

I hope you have found something useful in this post.  Please share your own suggestions or recommended tools / processes in the comments below.  Happy coding!

-Frog Out

Searching for Truncated Files in GitHub Folder

I’m sharing out this tip as I ran into this scenario recently.  If you are ever browsing through the GitHub website for files in a repo folder but get the warning “Sorry we had to truncate this directory… files were omitted from the list.” then this post may help.

 

Solution

I was recently browsing the Microsoft Graph .Net SDK repo through the GitHub website looking for the various Message functions.  Unfortunately the folder I was browsing has 6,000+ files and only the first 1,000 files are displayed (see highlighted box in following screenshot).  The first step in the solution is to click the “Find file” button in the upper right.

TruncatedFilesGHFolder1

 

On the following screen I typed “message” to filter the results for any files starting with that keyword.  Now I found the file I was looking for, “../MessageRequest.cs”.

TruncatedFilesGHFolder2

 

Conclusion

Looking back this may seem like an intuitive solution but I was stumped at first.  Hopefully this will help someone (or myself again) if they run into this.

-Frog Out

How To Edit Microsoft Documentation on GitHub

Recently I’ve been reading a lot of Microsoft official documentation, much of which has moved to hosting on GitHub.  If you didn’t know this move to GitHub also opens up the opportunity for anyone from the community to propose updates to the documentation through the GitHub pull request process.  This post will walk through the steps to make an edit of the documentation and submit a pull request.  Note this is not the only process to accomplish this but one that I’ve used with success recently.

Background

Additional resources for background on creating pull requests.

Creating a pull request
https://help.github.com/articles/creating-a-pull-request/

About pull requests
https://help.github.com/articles/about-pull-requests/

 

GitHub Pull Request Process

First ensure that you have a GitHub account (free or paid) that you can login to GItHub.com.

Signing up for a new GitHub account

https://help.github.com/articles/signing-up-for-a-new-github-account/

Next navigate to the documentation page you want to update (usually on the docs.microsoft.com domain).  Click the “Edit” button in upper right corner.

MSDocOnGitHub1

This will redirect you over to the underlying GitHub page where that file is sourced from.  Click the “pencil” icon to edit the file in question.

MSDocOnGitHub2

Make edits to the file as needed.

MSDocOnGitHub3

At the bottom of the page fill out a title and description for the file commit being proposed.  Click “Propose file change”.

MSDocOnGitHub4

You’ll see a summary of the commit being proposed with additions or deletions to the file at bottom.  Up top you can see which branch changes are coming from (yours) on the right and the branch to submit them to on the left (usually “master”).  Click “Create pull request” when ready.

MSDocOnGitHub5

You’ll be presented with a last page (not shown here) for the pull request prior to submitting.  Once submitted you should see the active pull request page with details about the checks being run and any comments from the approvers.  Here is an example of one that I submitted a few days ago.  Notice the “All check have passed” at bottom where a number of background checks run before the approvers even see the pull request.

MSDocOnGitHub6

 

Additional Resources

Microsoft Docs contributor guide overview
https://docs.microsoft.com/en-us/contribute

If you are editing a large number of files or want to work on them locally I would recommend installing the Docs Authoring Pack extension in Visual Studio Code.

Docs Authoring Pack for VS Code
https://docs.microsoft.com/en-us/contribute/how-to-write-docs-auth-pack

 

Conclusion

Hopefully after reading through this process you feel capable of making edits to official Microsoft documentation on GitHub and submitting pull requests.  Happy editing and share your knowledge with the world.

-Frog Out