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:

Y wald01001 /alguidelines Public 
forked from microsoft/alguidelines

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.

X M' index.md 
v ALGUIDEUNES 
> .github 
> archetypes 
v content 
> BCBestPractices 
v BCPatterns 
v Pattems 
index.md

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.

Y wald01001 /alguidelines Public 
forked from microsoft/alguidelines 
Code 
n 
Pull requests 
Actions 
Projects 
O 
Security 
Go to file 
n Contribute 
This branch is 2 commits ahead, 2 commits behind 
microsoft:main 
This branch is 2 commits ahead of 
Add fi 
29 mil 
wald0100 
.github/w 
archetype 
microsoft:main. 
Open a pull request to contribute your changes 
upstream. 
Open pull request

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:

Generic Method Pattern #27 
Ope 
wald01001 wants to merge 2 commits into microsoft:main from waldoleøl main C 
010) 
Conversation 
Commits 
wald01001 commented now 
No description provided 
Checks 
@ Files changed 
Collaborator 
wald01001 added 2 commits 2 days ago 
Generic Method Pattern - 
Initial Commit 
VI of the pattern 
Add more commits by pushing to the main branch on wald01001/alguidelines. 
This branch has not been deployed 
No deployments 
Review required 
At least 1 approving review is required by reviewers with write access. Learn more. 
Some checks haven't completed yet 
1 queued check 
O hugo Cl / deploy (pull_request) Queued— Waiting to run this check... 
Merging is blocked 
Merging can be performed automatically with 1 approving review. 
As an administrator, you may still merge this pull request. 
e48e7d8 
fb62a8b 
Hide all checks 
Details 
Merge pull request 
You can also open this in GitHub Desktop or view command line instructions.

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, .. .

5.00 avg. rating (97% score) - 1 vote

Permanent link to this article: https://www.waldo.be/2021/12/03/contributing-to-alguidelines-dev/

Leave a Reply

Your email address will not be published.

This site uses Akismet to reduce spam. Learn how your comment data is processed.