alguidelines.dev - Business Central Design Patterns – Contributing

Docs: Formatting tips

Mon, 01 Jan 0001 00:00:00 +0000

Tips and tricks in terms of working with MarkDown and Hugo

Markdown Cheat Sheet

Here you can find a rather interesting Cheat Sheet regarding markdown: https://www.markdownguide.org/cheat-sheet

Code Fences / Syntax highlighting

The syntax to use codefences is with backticks. If you provide the language after the first block of backticks, github will automatically put that in decent syntax highlighting. So, A simple code fence with AL code, can simply be done by:

```AL
procedure ALGuidelinesRock()
var
Customer: Record Customer;
begin
Customer.Get('10000');
Customer.Name := 'waldo';
Customer.Modify(true);
end;
```

Results in:

 procedure ALGuidelinesRock()
 var
 Customer: Record Customer;
 begin
 Customer.Get('10000');
 Customer.Name := 'waldo';
 Customer.Modify(true);
 end;

Hugo Shortcodes

Since we’re using “Hugo”, we can use it’s shortcode. Here is a reference: https://gohugo.io/content-management/shortcodes/

It basically means we are able to use easy notations to do cool things. Let’s point out some useful shortcodes:

Twitter

{{< tweet user="waldo1001" id="1458787011024805892" >}}

makes:

"Code is Poetry!"#msdyn365bc
— waldo (@waldo1001) November 11, 2021

YouTube

{{< youtube QVOMCYitLEc >}}

makes:

Figure

{{< figure src="http://www.waldo.be/wp-content/uploads/2021/11/business-central-logo.png" title="Business Central" >}}

makes:

Business Central

Docs: Guide to Fork & PR

Mon, 01 Jan 0001 00:00:00 +0000

Abstract

AL Guidelines is a community project, and as such YOU are encouraged to submit corrections and new ideas. In order to get your content included, you must submit a pull request to the GitHub Repository (Located here: https://github.com/microsoft/alguidelines). All Pull Requests are subject to approval by a minimum of three admins.

If You are toying with an idea, but You aren’t ready to create a document just yet, you are encouraged to create a project discussion thread here: https://github.com/microsoft/alguidelines/discussions

Warning

This is a warning. If You haven’t worked in collaboration with “external” GitHub repositories before, please familiarize yourself with that process by visiting:

https://docs.github.com/en/pull-requests/collaborating-with-pull-requests

Steps

Now that You have decided that You are ready to contribute, these are the steps to take.

Note

You can read more about this process here:

https://docs.github.com/en/get-started/quickstart/contributing-to-projects

Step 1: Fork

In order to work on the repository, You must Fork the repository.

By forking the repository, You essentially create a copy into Your own account.

Start by going to the GitHub Repository (https://github.com/microsoft/alguidelines), and press the Fork

Once You have successfully forked the repository, go to your own GitHub repository :

You are now able to clone your own repository to your local pc and start editing using your favorite editor. Visual Studio Code is perfectly fine for this task.

Note

You can read more about forking here:

https://docs.github.com/en/get-started/quickstart/fork-a-repo

Step 2: Branch

While not necessarily a must, it is always good practice to create a branch off of your forked repository. That will allow you to work on multiple contributions at the same time and won’t have to wait for pull requests to be approved before you can continue on your next contribution.

Note

You can read more about Branches here:

https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-branches

Step 3: Pull Request

Once you are happy with your contribution, it’s time to create a pull request to propose changes into the main project! This is the final step in producing a fork of someone else’s project, and arguably the most important. If you’ve made a change that you feel would benefit the community as a whole, you should definitely consider contributing back.

To do so, head on over to the repository on GitHub where your project lives. For this example, it would be at https://www.github.com/<your_username>/alguidelines. You’ll see a banner indicating that your branch is one commit ahead of microsoft:main. Click Contribute and then Open a pull request.

GitHub will bring you to a page that shows the differences between your fork and the microsoft/alguidelines repository. Click Create pull request.

GitHub will bring you to a page where you can enter a title and a description of your changes. It’s important to provide as much useful information and a rationale for why you’re making this pull request in the first place. The project owners needs to be able to determine whether your change is as useful to everyone as you think it is. Finally, click Create pull request.

Docs: Understanding the Approval Process

Mon, 01 Jan 0001 00:00:00 +0000

(coming soon)

Docs: Templates

Mon, 01 Jan 0001 00:00:00 +0000

We have created some template-files that you can simply copy and use. Look at them as “Patterns for describing patterns”

We currently offer the following templates:

for Patterns (raw)
for Best Practice (raw)

opening the “raw” link, will allow for the best copy/paste result.