Contributing to “ALGuidelines.Dev”

I recently blogged about this new initiative .. the revival of the “NAV Design Patterns Wiki”: ALGuidelines.Dev . Time to talk a bit more on how you can contribute. I’m documenting this while I’m writing my very first pattern (I admit, I had this blogpost laying around for a while ;-)).

Disclaimer

We do have a contribution-page here: “Guide to Fork & PR :: AL Guidelines” that kind of describes the same thing. I just wanted to describe it as a hands-on – and make some extra awareness ;-).

Fork

First, you should fork the repository. By forking, you actually create a new repository on your own GitHub account, which has a link to this one. You can simply do that with the button in the top right:

I simply forked this to my own github account: https://github.com/waldo1001/alguidelines. You see on the where it is forked from:

Clone

Next, what I simply do because I find it most convenient, is to clone it to my local pc, so I can work with local software to write the pattern. I will use VSCode (Duh.. ;-)).

Copy Template

In folder “content\Contributing\Templates\Patterns” you’ll find an index.md (all patterns will be written in an index.md, by the way) with a pattern to write a pattern (pun intended ;-)). I simply copy that folder to the “content\BCPatterns” folder.

Since I’ll be creating a pattern that is called “Generic Method Pattern”, I rename the folder to “generic-method-pattern” to comply with the naming convention of the other patterns.

Now, we need to describe the pattern in the index.md-file in that folder. Read it carefully – it should be quite straight forward. For any formatting tips, do know there is a page for that on the site, but the best tip would be to look around at the other patterns, and see what you can use, how it’s don in .md files, and do it similarly. You’ll find a lot of formatting tips just by reading through those patterns, like:

• How to use pictures
• How to use codefences
• How to embed a youtube video
• …

In any case – when you think you completely described the pattern the way you wanted, it’s time to get it to the site.

Commit & Push

First – we’ll have to make sure our own repo has the new code. Obviously simply commit & push your code to your github repo. This way, the code is in github. You don’t have to branch – in a way, since you’re working in your own repo, it’s a branch already ;-).

PullRequest

Since you have a fork to the repo at Microsoft, you can now create a pullrequest from your own repo.

Under the “contribute” button, you’ll find the “Open pull request” button to .. Uhm .. Create a pullrequest .

Now, it’s out of your hands. The PR will end up with the administrators and will start the review, comment and so on. Here’s an example of my pullrequest:

So .. there we go .. my first contribution all documented on how I did it :-). I hope this will help you taking the first step in contributing what is important for you in terms of code quality, patterns, best practices, .. .