152 lines
No EOL
16 KiB
XML
152 lines
No EOL
16 KiB
XML
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom"><channel><title>alguidelines.dev - Business Central Design Patterns – Contributing</title><link>https://alguidelines.dev/docs/contributing/</link><description>Recent content in Contributing on alguidelines.dev - Business Central Design Patterns</description><generator>Hugo -- gohugo.io</generator><language>en-us</language><atom:link href="https://alguidelines.dev/docs/contributing/index.xml" rel="self" type="application/rss+xml"/><item><title>Docs: Formatting tips</title><link>https://alguidelines.dev/docs/contributing/formattingtips/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://alguidelines.dev/docs/contributing/formattingtips/</guid><description>
|
||
<h1 id="tips-and-tricks-in-terms-of-working-with-markdown-and-hugo">Tips and tricks in terms of working with MarkDown and Hugo</h1>
|
||
<h2 id="markdown-cheat-sheet">Markdown Cheat Sheet</h2>
|
||
<p>Here you can find a rather interesting Cheat Sheet regarding markdown: <a href="https://www.markdownguide.org/cheat-sheet">https://www.markdownguide.org/cheat-sheet</a></p>
|
||
<h2 id="code-fences--syntax-highlighting">Code Fences / Syntax highlighting</h2>
|
||
<p>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:</p>
|
||
<pre tabindex="0"><code>```AL
|
||
procedure ALGuidelinesRock()
|
||
var
|
||
Customer: Record Customer;
|
||
begin
|
||
Customer.Get(&#39;10000&#39;);
|
||
Customer.Name := &#39;waldo&#39;;
|
||
Customer.Modify(true);
|
||
end;
|
||
```
|
||
</code></pre><p>Results in:</p>
|
||
<div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-AL" data-lang="AL"><span style="display:flex;"><span><span style="color:#f8f8f8;text-decoration:underline"> </span><span style="color:#204a87;font-weight:bold">procedure</span><span style="color:#f8f8f8;text-decoration:underline"> </span>ALGuidelinesRock<span style="color:#ce5c00;font-weight:bold">()
|
||
</span></span></span><span style="display:flex;"><span><span style="color:#ce5c00;font-weight:bold"> </span><span style="color:#204a87;font-weight:bold">var</span><span style="color:#f8f8f8;text-decoration:underline">
|
||
</span></span></span><span style="display:flex;"><span><span style="color:#f8f8f8;text-decoration:underline"> </span>Customer<span style="color:#000;font-weight:bold">:</span><span style="color:#f8f8f8;text-decoration:underline"> </span><span style="color:#204a87;font-weight:bold">Record</span><span style="color:#f8f8f8;text-decoration:underline"> </span>Customer<span style="color:#000;font-weight:bold">;</span><span style="color:#f8f8f8;text-decoration:underline">
|
||
</span></span></span><span style="display:flex;"><span><span style="color:#f8f8f8;text-decoration:underline"> </span><span style="color:#204a87;font-weight:bold">begin</span><span style="color:#f8f8f8;text-decoration:underline">
|
||
</span></span></span><span style="display:flex;"><span><span style="color:#f8f8f8;text-decoration:underline"> </span>Customer<span style="color:#ce5c00;font-weight:bold">.</span>Get<span style="color:#ce5c00;font-weight:bold">(</span><span style="color:#4e9a06">&#39;10000&#39;</span><span style="color:#ce5c00;font-weight:bold">)</span><span style="color:#000;font-weight:bold">;</span><span style="color:#f8f8f8;text-decoration:underline">
|
||
</span></span></span><span style="display:flex;"><span><span style="color:#f8f8f8;text-decoration:underline"> </span>Customer<span style="color:#ce5c00;font-weight:bold">.</span>Name<span style="color:#f8f8f8;text-decoration:underline"> </span><span style="color:#ce5c00;font-weight:bold">:=</span><span style="color:#f8f8f8;text-decoration:underline"> </span><span style="color:#4e9a06">&#39;waldo&#39;</span><span style="color:#000;font-weight:bold">;</span><span style="color:#f8f8f8;text-decoration:underline">
|
||
</span></span></span><span style="display:flex;"><span><span style="color:#f8f8f8;text-decoration:underline"> </span>Customer<span style="color:#ce5c00;font-weight:bold">.</span><span style="color:#204a87;font-weight:bold">Modify</span><span style="color:#ce5c00;font-weight:bold">(</span>true<span style="color:#ce5c00;font-weight:bold">)</span><span style="color:#000;font-weight:bold">;</span><span style="color:#f8f8f8;text-decoration:underline">
|
||
</span></span></span><span style="display:flex;"><span><span style="color:#f8f8f8;text-decoration:underline"> </span><span style="color:#204a87;font-weight:bold">end</span><span style="color:#000;font-weight:bold">;</span><span style="color:#f8f8f8;text-decoration:underline">
|
||
</span></span></span></code></pre></div><h2 id="diagrams-with-mermaid">Diagrams with Mermaid</h2>
|
||
<p>When providing a documentation, diagrams come in handy. <a href="https://mermaid-js.github.io/mermaid/#/">Mermaid</a> lets you create diagrams and visualizations using text and code.</p>
|
||
<p>For example the following markdown section:</p>
|
||
<pre tabindex="0"><code>```mermaid
|
||
classDiagram
|
||
Animal &lt;|-- Duck
|
||
Animal &lt;|-- Fish
|
||
Animal &lt;|-- Zebra
|
||
Animal : +int age
|
||
Animal : +String gender
|
||
Animal: +isMammal()
|
||
Animal: +mate()
|
||
class Duck{
|
||
+String beakColor
|
||
+swim()
|
||
+quack()
|
||
}
|
||
class Fish{
|
||
-int sizeInFeet
|
||
-canEat()
|
||
}
|
||
class Zebra{
|
||
+bool is_wild
|
||
+run()
|
||
}
|
||
```
|
||
</code></pre><p>Results in:</p>
|
||
<pre tabindex="0"><code class="language-mermaid" data-lang="mermaid">classDiagram
|
||
Animal &lt;|-- Duck
|
||
Animal &lt;|-- Fish
|
||
Animal &lt;|-- Zebra
|
||
Animal : +int age
|
||
Animal : +String gender
|
||
Animal: +isMammal()
|
||
Animal: +mate()
|
||
class Duck{
|
||
+String beakColor
|
||
+swim()
|
||
+quack()
|
||
}
|
||
class Fish{
|
||
-int sizeInFeet
|
||
-canEat()
|
||
}
|
||
class Zebra{
|
||
+bool is_wild
|
||
+run()
|
||
}
|
||
</code></pre><p>Can&rsquo;t wait to get started? Use the Mermaid <a href="https://mermaid.live/edit">Live Editor</a>.</p>
|
||
<h2 id="hugo-shortcodes">Hugo Shortcodes</h2>
|
||
<p>Since we&rsquo;re using &ldquo;Hugo&rdquo;, we can use it&rsquo;s shortcode. Here is a reference: <a href="https://gohugo.io/content-management/shortcodes/">https://gohugo.io/content-management/shortcodes/</a></p>
|
||
<p>It basically means we are able to use easy notations to do cool things. Let&rsquo;s point out some useful shortcodes:</p>
|
||
<h3 id="twitter">Twitter</h3>
|
||
<pre tabindex="0"><code>{{&lt; tweet user=&#34;waldo1001&#34; id=&#34;1458787011024805892&#34; &gt;}}
|
||
</code></pre><p>makes:
|
||
<blockquote class="twitter-tweet"><p lang="en" dir="ltr">&quot;Code is Poetry!&quot;<a href="https://twitter.com/hashtag/msdyn365bc?src=hash&amp;ref_src=twsrc%5Etfw">#msdyn365bc</a></p>&mdash; waldo (@waldo1001) <a href="https://twitter.com/waldo1001/status/1458787011024805892?ref_src=twsrc%5Etfw">November 11, 2021</a></blockquote>
|
||
<script async src="https://platform.twitter.com/widgets.js" charset="utf-8"></script>
|
||
</p>
|
||
<h3 id="youtube">YouTube</h3>
|
||
<pre tabindex="0"><code>{{&lt; youtube QVOMCYitLEc &gt;}}
|
||
</code></pre><p>makes:
|
||
<div style="position: relative; padding-bottom: 56.25%; height: 0; overflow: hidden;">
|
||
<iframe src="https://www.youtube.com/embed/QVOMCYitLEc" style="position: absolute; top: 0; left: 0; width: 100%; height: 100%; border:0;" allowfullscreen title="YouTube Video"></iframe>
|
||
</div>
|
||
</p>
|
||
<h3 id="figure">Figure</h3>
|
||
<pre tabindex="0"><code>{{&lt; figure src=&#34;http://www.waldo.be/wp-content/uploads/2021/11/business-central-logo.png&#34; title=&#34;Business Central&#34; &gt;}}
|
||
</code></pre><p>makes:
|
||
<figure>
|
||
<img src="http://www.waldo.be/wp-content/uploads/2021/11/business-central-logo.png"/> <figcaption>
|
||
<h4>Business Central</h4>
|
||
</figcaption>
|
||
</figure>
|
||
</p></description></item><item><title>Docs: Guide to Fork & PR</title><link>https://alguidelines.dev/docs/contributing/forkandpr/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://alguidelines.dev/docs/contributing/forkandpr/</guid><description>
|
||
<h2 id="abstract">Abstract</h2>
|
||
<p>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: <a href="https://github.com/microsoft/alguidelines">https://github.com/microsoft/alguidelines</a>). All Pull Requests are subject to approval by a minimum of three admins.</p>
|
||
<p>If You are toying with an idea, but You aren&rsquo;t ready to create a document just yet, you are encouraged to create a project discussion thread here: <a href="https://github.com/microsoft/alguidelines/discussions">https://github.com/microsoft/alguidelines/discussions</a></p>
|
||
<div class="alert alert-warning" role="alert">
|
||
<h4 class="alert-heading">Warning</h4>
|
||
<p>This is a warning.
|
||
If You haven&rsquo;t worked in collaboration with &ldquo;external&rdquo; GitHub repositories before, please familiarize yourself with that process by visiting:</p>
|
||
<p><a href="https://docs.github.com/en/pull-requests/collaborating-with-pull-requests">https://docs.github.com/en/pull-requests/collaborating-with-pull-requests</a></p>
|
||
</div>
|
||
<h2 id="steps">Steps</h2>
|
||
<p>Now that You have decided that You are ready to contribute, these are the steps to take.
|
||
<div class="alert alert-info" role="alert">
|
||
<h4 class="alert-heading">Note</h4>
|
||
<p>You can read more about this process here:</p>
|
||
<p><a href="https://docs.github.com/en/get-started/quickstart/contributing-to-projects">https://docs.github.com/en/get-started/quickstart/contributing-to-projects</a></p>
|
||
</div>
|
||
</p>
|
||
<h3 id="step-1-fork">Step 1: Fork</h3>
|
||
<p>In order to work on the repository, You must <a href="https://docs.github.com/en/get-started/quickstart/fork-a-repo">Fork</a> the repository.</p>
|
||
<p>By forking the repository, You essentially create a copy into Your own account.</p>
|
||
<p>Start by going to the GitHub Repository (<a href="https://github.com/microsoft/alguidelines">https://github.com/microsoft/alguidelines</a>), and press the Fork <img src="./fork_button.jpg" alt="Fork Button" title="Fork"></p>
|
||
<p>Once You have successfully forked the repository, go to your own GitHub repository : <img src="./ForkedRepro.png" alt="Forked Repository Representation" title="Forked repository"></p>
|
||
<p>You are now able to clone your own repository to your local pc and start editing using your favorite editor. <a href="https://code.visualstudio.com/">Visual Studio Code</a> is perfectly fine for this task.</p>
|
||
<div class="alert alert-info" role="alert">
|
||
<h4 class="alert-heading">Note</h4>
|
||
<p>You can read more about forking here:</p>
|
||
<p><a href="https://docs.github.com/en/get-started/quickstart/fork-a-repo">https://docs.github.com/en/get-started/quickstart/fork-a-repo</a></p>
|
||
</div>
|
||
<h3 id="step-2-branch">Step 2: Branch</h3>
|
||
<p>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&rsquo;t have to wait for pull requests to be approved before you can continue on your next contribution.</p>
|
||
<div class="alert alert-info" role="alert">
|
||
<h4 class="alert-heading">Note</h4>
|
||
<p>You can read more about Branches here:</p>
|
||
<p><a href="https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-branches">https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-branches</a></p>
|
||
</div>
|
||
<h3 id="step-3-pull-request">Step 3: Pull Request</h3>
|
||
<p>Once you are happy with your contribution, it&rsquo;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&rsquo;s project, and arguably the most important. If you&rsquo;ve made a change that you feel would benefit the community as a whole, you should definitely consider contributing back.</p>
|
||
<p>To do so, head on over to the repository on GitHub where your project lives. For this example, it would be at <code>https://www.github.com/&lt;your_username&gt;/alguidelines</code>. You&rsquo;ll see a banner indicating that your branch is one commit ahead of microsoft:main. Click <strong>Contribute</strong> and then <strong>Open a pull request.</strong></p>
|
||
<p>GitHub will bring you to a page that shows the differences between your fork and the microsoft/alguidelines repository. Click <strong>Create pull request.</strong></p>
|
||
<p>GitHub will bring you to a page where you can enter a title and a description of your changes. <em>It&rsquo;s important to provide as much useful information and a rationale for why you&rsquo;re making this pull request in the first place.</em> The project owners needs to be able to determine whether your change is as useful to everyone as you think it is. Finally, click <strong>Create pull request.</strong></p></description></item><item><title>Docs: Understanding the Approval Process</title><link>https://alguidelines.dev/docs/contributing/theapprovalprocess/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://alguidelines.dev/docs/contributing/theapprovalprocess/</guid><description>
|
||
<p>(coming soon)</p></description></item><item><title>Docs: Install Hugo</title><link>https://alguidelines.dev/docs/contributing/installhugo/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://alguidelines.dev/docs/contributing/installhugo/</guid><description>
|
||
<p>There are multiple ways to install Hugo for you to properly preview your contributions. Please select the scenario that matches your setup.</p>
|
||
<p>For the official install guide, you can visit <a href="https://gohugo.io/getting-started/installing/">https://gohugo.io/getting-started/installing/</a></p>
|
||
<div style="position: relative; padding-bottom: 56.25%; height: 0; overflow: hidden;">
|
||
<iframe src="https://www.youtube.com/embed/G7umPCU-8xc" style="position: absolute; top: 0; left: 0; width: 100%; height: 100%; border:0;" allowfullscreen title="YouTube Video"></iframe>
|
||
</div></description></item><item><title>Docs: Templates</title><link>https://alguidelines.dev/docs/contributing/templates/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://alguidelines.dev/docs/contributing/templates/</guid><description>
|
||
<p>We have created some template-files that you can simply copy and use. Look at them as &ldquo;Patterns for describing patterns&rdquo;</p>
|
||
<p>We currently offer the following templates:</p>
|
||
<ul>
|
||
<li>for <a href="https://alguidelines.dev/contributing/templates/patterns/">Patterns</a> (<a href="https://raw.githubusercontent.com/microsoft/alguidelines/main/content/docs/Contributing/Templates/Patterns/index.md">raw</a>)</li>
|
||
<li>for <a href="https://alguidelines.dev/contributing/templates/bestpractice/">Best Practice</a> (<a href="https://raw.githubusercontent.com/microsoft/alguidelines/main/content/docs/Contributing/Templates/BestPractice/index.md">raw</a>)</li>
|
||
</ul>
|
||
<p>opening the &ldquo;raw&rdquo; link, will allow for the best copy/paste result.</p></description></item></channel></rss> |