mirror of
https://github.com/asdf-vm/asdf.git
synced 2024-12-19 18:05:02 -07:00
40 lines
17 KiB
JavaScript
40 lines
17 KiB
JavaScript
import{_ as e,c as a,a2 as i,o as t}from"./chunks/framework.BQmytedh.js";const g=JSON.parse('{"title":"asdf","description":"","frontmatter":{},"headers":[],"relativePath":"contribute/core.md","filePath":"contribute/core.md","lastUpdated":1728309110000}'),n={name:"contribute/core.md"};function l(o,s,p,r,h,d){return t(),a("div",null,s[0]||(s[0]=[i(`<h1 id="asdf" tabindex="-1">asdf <a class="header-anchor" href="#asdf" aria-label="Permalink to "asdf""></a></h1><p><code>asdf</code> core contribution guide.</p><h2 id="initial-setup" tabindex="-1">Initial Setup <a class="header-anchor" href="#initial-setup" aria-label="Permalink to "Initial Setup""></a></h2><p>Fork <code>asdf</code> on GitHub and/or Git clone the default branch:</p><div class="language-shell vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">shell</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># clone your fork</span></span>
|
||
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">git</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> clone</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> https://github.com/</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"><</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">GITHUB_USE</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">R</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">></span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">/asdf.git</span></span>
|
||
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># or clone asdf</span></span>
|
||
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">git</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> clone</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> https://github.com/asdf-vm/asdf.git</span></span></code></pre></div><p>The tools for core development are in this repo's <code>.tool-versions</code>. If you wish to manage with <code>asdf</code> itself, add the plugins:</p><div class="language-shell vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">shell</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">asdf</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> plugin</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> add</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> bats</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> https://github.com/timgluz/asdf-bats.git</span></span>
|
||
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">asdf</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> plugin</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> add</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> shellcheck</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> https://github.com/luizm/asdf-shellcheck.git</span></span>
|
||
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">asdf</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> plugin</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> add</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> shfmt</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> https://github.com/luizm/asdf-shfmt.git</span></span></code></pre></div><p>Install the versions to develop <code>asdf</code> with:</p><div class="language-shell vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">shell</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">asdf</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> install</span></span></code></pre></div><p>It <em>may</em> be useful to not use <code>asdf</code> to manage the tools during development on your local machine as you may need to break functionality which would then break your dev tooling. Here's the raw list of tools:</p><ul><li><a href="https://github.com/bats-core/bats-core" target="_blank" rel="noreferrer">bats-core</a>: Bash Automated Testing System, for unit testing Bash or POSIX compliant scripts.</li><li><a href="https://github.com/koalaman/shellcheck" target="_blank" rel="noreferrer">shellcheck</a>: Static analysis tool for shell scripts.</li><li><a href="https://github.com/mvdan/sh" target="_blank" rel="noreferrer">shfmt</a>: A shell parser, formatter, and interpreter with bash support; includes shfmt</li></ul><h2 id="development" tabindex="-1">Development <a class="header-anchor" href="#development" aria-label="Permalink to "Development""></a></h2><p>If you want to try out your changes without making change to your installed <code>asdf</code>, you can set the <code>$ASDF_DIR</code> variable to the path where you cloned the repository, and temporarily prepend the <code>bin</code> and <code>shims</code> directory of the directory to your path.</p><p>It is best to format, lint and test your code locally before you commit or push to the remote. Use the following scripts/commands:</p><div class="language-shell vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">shell</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Lint</span></span>
|
||
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">./scripts/lint.bash</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --check</span></span>
|
||
<span class="line"></span>
|
||
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Fix & Format</span></span>
|
||
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">./scripts/lint.bash</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --fix</span></span>
|
||
<span class="line"></span>
|
||
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Test: all tests</span></span>
|
||
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">./scripts/test.bash</span></span>
|
||
<span class="line"></span>
|
||
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Test: for specific command</span></span>
|
||
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">bats</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> test/list_commands.bash</span></span></code></pre></div><div class="tip custom-block"><p class="custom-block-title">TIP</p><p><strong>Add tests!</strong> - Tests are <strong>required</strong> for new features and speed up review of bug fixes. Please cover new code paths before you create a Pull Request. See <a href="https://bats-core.readthedocs.io/en/stable/index.html" target="_blank" rel="noreferrer">bats-core documentation</a></p></div><h3 id="gitignore" tabindex="-1">Gitignore <a class="header-anchor" href="#gitignore" aria-label="Permalink to "Gitignore""></a></h3><p>The following is the <code>.gitignore</code> file in the <code>asdf-vm/asdf</code> repository. We ignore project-specific files. Files specific to your OS, tools or workflows should be ignored in your global <code>.gitignore</code> configuration, <a href="http://stratus3d.com/blog/2018/06/03/stop-excluding-editor-temp-files-in-gitignore/" target="_blank" rel="noreferrer">see here</a> for more details.</p><div class="language-gitignore vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">gitignore</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>/installs</span></span>
|
||
<span class="line"><span>/downloads</span></span>
|
||
<span class="line"><span>/shims</span></span>
|
||
<span class="line"><span>repository</span></span>
|
||
<span class="line"><span>.vagrant</span></span>
|
||
<span class="line"><span>keyrings</span></span>
|
||
<span class="line"><span>/tmp</span></span>
|
||
<span class="line"><span></span></span>
|
||
<span class="line"><span>dist/</span></span></code></pre></div><h3 id="git-blame-ignore-revs" tabindex="-1"><code>.git-blame-ignore-revs</code> <a class="header-anchor" href="#git-blame-ignore-revs" aria-label="Permalink to "\`.git-blame-ignore-revs\`""></a></h3><p><code>asdf</code> uses a <code>.git-blame-ignore-revs</code> to reduce noise when running a blame. See the <a href="https://git-scm.com/docs/git-blame" target="_blank" rel="noreferrer">git blame documentation</a> for more information.</p><p>Use the file with <code>git blame</code> like so:</p><div class="language-sh vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">sh</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">git</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> blame</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --ignore-revs-file</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .git-blame-ignore-revs</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ./test/install_command.bats</span></span></code></pre></div><p>Optionally, configure to use the file on every invocation of <code>blame</code> without manually supplying it:</p><div class="language-sh vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">sh</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">git</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> config</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> blame.ignoreRevsFile</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .git-blame-ignore-revs</span></span></code></pre></div><p>It is possible to configure IDEs to use this file. For example, when using VSCode (with <a href="https://marketplace.visualstudio.com/items?itemName=eamodio.gitlens" target="_blank" rel="noreferrer">GitLens</a>), write the following to <code>.vscode/settings.json</code>:</p><div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span></span>
|
||
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "gitlens.advanced.blame.customArguments"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [</span></span>
|
||
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "--ignore-revs-file"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
||
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ".git-blame-ignore-revs"</span></span>
|
||
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ]</span></span>
|
||
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><h2 id="bats-testing" tabindex="-1">Bats Testing <a class="header-anchor" href="#bats-testing" aria-label="Permalink to "Bats Testing""></a></h2><p>Execute tests locally with:</p><div class="language-shell vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">shell</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">./scripts/test.bash</span></span></code></pre></div><p>Before writing tests <strong>please read</strong>:</p><ul><li>existing tests in <code>test/</code></li><li><a href="https://bats-core.readthedocs.io/en/stable/index.html" target="_blank" rel="noreferrer">bats-core documentation</a></li><li>existing Bats settings used in <code>scripts/test.bash</code></li></ul><h3 id="bats-tips" tabindex="-1">Bats Tips <a class="header-anchor" href="#bats-tips" aria-label="Permalink to "Bats Tips""></a></h3><p>Bats debugging can be difficult at times. Using the TAP output with <code>-t</code> flag will enable you to print outputs with the special file descriptor <code>>&3</code> during test execution, simplifying debugging. As an example:</p><div class="language-shell vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">shell</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># test/some_tests.bats</span></span>
|
||
<span class="line"></span>
|
||
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">printf</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "%s\\n"</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "Will not be printed during bats test/some_tests.bats"</span></span>
|
||
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">printf</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "%s\\n"</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "Will be printed during bats -t test/some_tests.bats"</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> >&3</span></span></code></pre></div><p>This is further documented in bats-core <a href="https://bats-core.readthedocs.io/en/stable/writing-tests.html#printing-to-the-terminal" target="_blank" rel="noreferrer">Printing to the Terminal</a>.</p><h2 id="pull-requests-releases-conventional-commits" tabindex="-1">Pull Requests, Releases & Conventional Commits <a class="header-anchor" href="#pull-requests-releases-conventional-commits" aria-label="Permalink to "Pull Requests, Releases & Conventional Commits""></a></h2><p><code>asdf</code> is using an automated release tool called <a href="https://github.com/googleapis/release-please" target="_blank" rel="noreferrer">Release Please</a> to automatically bump the <a href="https://semver.org/" target="_blank" rel="noreferrer">SemVer</a> version and generate the <a href="https://github.com/asdf-vm/asdf/blob/master/CHANGELOG.md" target="_blank" rel="noreferrer">Changelog</a>. This information is determined by reading the commit history since the last release.</p><p><a href="https://www.conventionalcommits.org/" target="_blank" rel="noreferrer">Conventional Commit messages</a> define the format of the Pull Request Title which becomes the commit message format on the default branch. This is enforced with GitHub Action <a href="https://github.com/amannn/action-semantic-pull-request" target="_blank" rel="noreferrer"><code>amannn/action-semantic-pull-request</code></a>.</p><p>Conventional Commit follows this format:</p><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span><type>[optional scope][optional !]: <description></span></span>
|
||
<span class="line"><span></span></span>
|
||
<span class="line"><span><!-- examples --></span></span>
|
||
<span class="line"><span>fix: some fix</span></span>
|
||
<span class="line"><span>feat: a new feature</span></span>
|
||
<span class="line"><span>docs: some documentation update</span></span>
|
||
<span class="line"><span>docs(website): some change for the website</span></span>
|
||
<span class="line"><span>feat!: feature with breaking change</span></span></code></pre></div><p>The full list of <code><types></code> are: <code>feat</code>, <code>fix</code>, <code>docs</code>, <code>style</code>, <code>refactor</code>, <code>perf</code>, <code>test</code>, <code>build</code>, <code>ci</code>, <code>chore</code>, <code>revert</code>.</p><ul><li><code>!</code>: indicates a breaking change</li><li><code>fix</code>: will create a new SemVer <code>patch</code></li><li><code>feat</code>: will create a new SemVer <code>minor</code></li><li><code><type>!</code>: will create a new SemVer <code>major</code></li></ul><p>The Pull Request Title must follow this format.</p><div class="tip custom-block"><p class="custom-block-title">TIP</p><p>Use Conventional Commit message format for your Pull Request Title.</p></div><h2 id="docker-images" tabindex="-1">Docker Images <a class="header-anchor" href="#docker-images" aria-label="Permalink to "Docker Images""></a></h2><p>The <a href="https://github.com/vic/asdf-alpine" target="_blank" rel="noreferrer">asdf-alpine</a> and <a href="https://github.com/vic/asdf-ubuntu" target="_blank" rel="noreferrer">asdf-ubuntu</a> projects are an ongoing effort to provide Dockerized images of some asdf tools. You can use these docker images as base for your development servers, or for running your production apps.</p>`,47)]))}const k=e(n,[["render",l]]);export{g as __pageData,k as default};
|