hookshot/5.2.1/contributing.html

351 lines
24 KiB
HTML
Raw Permalink Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE HTML>
<html lang="en" class="sidebar-visible no-js light">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Contributing - Matrix Hookshot</title>
<!-- Custom HTML head -->
<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
<meta name="description" content="">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="theme-color" content="#ffffff" />
<link rel="icon" href="favicon.svg">
<link rel="shortcut icon" href="favicon.png">
<link rel="stylesheet" href="css/variables.css">
<link rel="stylesheet" href="css/general.css">
<link rel="stylesheet" href="css/chrome.css">
<link rel="stylesheet" href="css/print.css" media="print">
<!-- Fonts -->
<link rel="stylesheet" href="FontAwesome/css/font-awesome.css">
<link rel="stylesheet" href="fonts/fonts.css">
<!-- Highlight.js Stylesheets -->
<link rel="stylesheet" href="highlight.css">
<link rel="stylesheet" href="tomorrow-night.css">
<link rel="stylesheet" href="ayu-highlight.css">
<!-- Custom theme stylesheets -->
<link rel="stylesheet" href="docs/_site/style.css">
</head>
<body>
<!-- Provide site root to javascript -->
<script type="text/javascript">
var path_to_root = "";
var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
</script>
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script type="text/javascript">
try {
var theme = localStorage.getItem('mdbook-theme');
var sidebar = localStorage.getItem('mdbook-sidebar');
if (theme.startsWith('"') && theme.endsWith('"')) {
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
}
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
}
} catch (e) { }
</script>
<!-- Set the theme before any content is loaded, prevents flash -->
<script type="text/javascript">
var theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
var html = document.querySelector('html');
html.classList.remove('no-js')
html.classList.remove('light')
html.classList.add(theme);
html.classList.add('js');
</script>
<!-- Hide / unhide sidebar before it is displayed -->
<script type="text/javascript">
var html = document.querySelector('html');
var sidebar = 'hidden';
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
}
html.classList.remove('sidebar-visible');
html.classList.add("sidebar-" + sidebar);
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<div class="sidebar-scrollbox">
<ol class="chapter"><li class="chapter-item expanded "><a href="hookshot.html"><strong aria-hidden="true">1.</strong> Hookshot</a></li><li class="chapter-item expanded "><a href="setup.html"><strong aria-hidden="true">2.</strong> ⚙️ Setup</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="setup/sample-configuration.html"><strong aria-hidden="true">2.1.</strong> 📃 Sample Configuration</a></li><li class="chapter-item expanded "><a href="setup/feeds.html"><strong aria-hidden="true">2.2.</strong> Feeds</a></li><li class="chapter-item expanded "><a href="setup/figma.html"><strong aria-hidden="true">2.3.</strong> Figma</a></li><li class="chapter-item expanded "><a href="setup/github.html"><strong aria-hidden="true">2.4.</strong> GitHub</a></li><li class="chapter-item expanded "><a href="setup/gitlab.html"><strong aria-hidden="true">2.5.</strong> GitLab</a></li><li class="chapter-item expanded "><a href="setup/jira.html"><strong aria-hidden="true">2.6.</strong> JIRA</a></li><li class="chapter-item expanded "><a href="setup/webhooks.html"><strong aria-hidden="true">2.7.</strong> Webhooks</a></li></ol></li><li class="chapter-item expanded "><a href="usage.html"><strong aria-hidden="true">3.</strong> 👤 Usage</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="usage/dynamic_rooms.html"><strong aria-hidden="true">3.1.</strong> Dynamic Rooms</a></li><li class="chapter-item expanded "><a href="usage/auth.html"><strong aria-hidden="true">3.2.</strong> Authenticating</a></li><li class="chapter-item expanded "><a href="usage/room_configuration.html"><strong aria-hidden="true">3.3.</strong> Room Configuration</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="usage/room_configuration/github_repo.html"><strong aria-hidden="true">3.3.1.</strong> GitHub Repo</a></li><li class="chapter-item expanded "><a href="usage/room_configuration/gitlab_project.html"><strong aria-hidden="true">3.3.2.</strong> GitLab Project</a></li><li class="chapter-item expanded "><a href="usage/room_configuration/jira_project.html"><strong aria-hidden="true">3.3.3.</strong> JIRA Project</a></li></ol></li></ol></li><li class="chapter-item expanded "><a href="metrics.html"><strong aria-hidden="true">4.</strong> 📊 Metrics</a></li><li class="chapter-item expanded "><a href="sentry.html"><strong aria-hidden="true">5.</strong> Sentry</a></li><li class="chapter-item expanded "><a href="troubleshooting.html"><strong aria-hidden="true">6.</strong> 🆘 Troubleshooting</a></li><li class="chapter-item expanded affix "><li class="part-title">🧑‍💻 Development</li><li class="chapter-item expanded "><a href="contributing.html" class="active"><strong aria-hidden="true">7.</strong> Contributing</a></li><li class="chapter-item expanded affix "><li class="part-title">🥼 Advanced</li><li class="chapter-item expanded "><a href="advanced/provisioning.html"><strong aria-hidden="true">8.</strong> Provisioning</a></li><li class="chapter-item expanded "><a href="advanced/workers.html"><strong aria-hidden="true">9.</strong> Workers</a></li><li class="chapter-item expanded "><a href="advanced/encryption.html"><strong aria-hidden="true">10.</strong> 🔒 Encryption</a></li><li class="chapter-item expanded "><a href="advanced/widgets.html"><strong aria-hidden="true">11.</strong> 🪀 Widgets</a></li><li class="chapter-item expanded "><a href="advanced/service_bots.html"><strong aria-hidden="true">12.</strong> Service Bots</a></li></ol> </div>
<div id="sidebar-resize-handle" class="sidebar-resize-handle"></div>
</nav>
<div id="page-wrapper" class="page-wrapper">
<div class="page">
<div id="menu-bar-hover-placeholder"></div>
<div id="menu-bar" class="menu-bar sticky bordered">
<div class="left-buttons">
<button id="sidebar-toggle" class="icon-button" type="button" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</button>
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
<i class="fa fa-paint-brush"></i>
</button>
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
<li role="none"><button role="menuitem" class="theme" id="light">Light (default)</button></li>
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
</ul>
<button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
<i class="fa fa-search"></i>
</button>
</div>
<h1 class="menu-title">Matrix Hookshot</h1>
<div class="right-buttons">
<a href="print.html" title="Print this book" aria-label="Print this book">
<i id="print-button" class="fa fa-print"></i>
</a>
<a href="https://github.com/matrix-org/matrix-hookshot" title="Git repository" aria-label="Git repository">
<i id="git-repository-button" class="fa fa-github"></i>
</a>
<a href="https://github.com/matrix-org/matrix-hookshot/edit/main/docs/contributing.md" title="Suggest an edit" aria-label="Suggest an edit">
<i id="git-edit-button" class="fa fa-edit"></i>
</a>
</div>
</div>
<div id="search-wrapper" class="hidden">
<form id="searchbar-outer" class="searchbar-outer">
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
</form>
<div id="searchresults-outer" class="searchresults-outer hidden">
<div id="searchresults-header" class="searchresults-header"></div>
<ul id="searchresults">
</ul>
</div>
</div>
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
<script type="text/javascript">
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
});
</script>
<div id="content" class="content">
<main>
<h1 id="contributing"><a class="header" href="#contributing">Contributing</a></h1>
<h2 id="matrixorg-bridges"><a class="header" href="#matrixorg-bridges">Matrix.org Bridges</a></h2>
<h1 id="contributing-1"><a class="header" href="#contributing-1">Contributing</a></h1>
<p>Hello there 👋. This contributing file is used amongst the matrix.org bridge repositories and should be followed when
making any contribution. If you are reading this, that means you are going to be contributing to some free software,
and that's great! Thank you!</p>
<h2 id="-getting-in-touch"><a class="header" href="#-getting-in-touch">🗨️ Getting in touch</a></h2>
<p>As a Matrix-based project we use chat rooms heavily for coordinating work. When getting involved with an issue or pull
request, feel free to reach out to us in one of the project rooms. The project room for the repository you are working
on should be visible from the README.md file.</p>
<p>Be aware that by interacting with our Matrix rooms and/or GitHub repositories, you are agreeing to abide by the
<a href="https://matrix.org/legal/code-of-conduct">Matrix.org code of conduct</a>.</p>
<h2 id="-filing-issues"><a class="header" href="#-filing-issues">✍️ Filing issues</a></h2>
<p>We use the GitHub issue tracker for issue filing. A good issue can mean the difference between a quick fix and a long,
painful fixing process. That's why the following guidelines exist:</p>
<ul>
<li>If you are reporting a bug:
<ul>
<li>Write a short title which neatly summaries the <em>problem</em>.
Do <strong>not</strong> write the <em>solution</em> in the issue title.
For example: <code>Cannot create a nick with | in it</code> is a good issue title. <code>Filter nicks according to RFC 2812</code>
is not a good issue title.</li>
<li>Give a summary and as much information (along with proposed solutions) as possible in the description of the issue.</li>
<li>Please either mention which version of the bridge you are using, or the commit hash.</li>
</ul>
</li>
<li>If it's a feature:
<ul>
<li>Your title should be a quick summary such as &quot;Add ability to send encrypted files&quot;</li>
<li>Your description should describe the outcome, not the solution.
<ul>
<li>For instance: &quot;A function exists which can be used to send encrypted files to Matrix rooms&quot;.</li>
<li>Not: &quot;There should be a MatrixClient.sendEncryptedFile() so the Foobar bridge can send encrypted images&quot;</li>
</ul>
</li>
</ul>
</li>
</ul>
<p>Issues will be categorised according to <a href="https://github.com/matrix-org/synapse/issues/9460">Synapse's rules</a>. To summarise:</p>
<ul>
<li>Your issue will be catagorised as one of the following types by the maintainer team:
<ul>
<li><strong>T-Defect</strong>: Bugs, crashes, hangs, vulnerabilities, or other reported problems.</li>
<li><strong>T-Enhancement</strong>: New features, changes in functionality, performance boosts, user-facing improvements.</li>
<li><strong>T-Documentation</strong>: Improvements or additions to documentation.</li>
</ul>
</li>
<li>You <em>may</em> have a severity assigned as an estimate to understand how bad the problem is and how many users are affected.</li>
</ul>
<p>The assigned labels are at the maintainers' discretion, and we will make every effort to be transparent when triaging.
We do not, as a rule, assign priority labeling to issues.</p>
<h2 id="contributing-documentation"><a class="header" href="#contributing-documentation">Contributing documentation</a></h2>
<p>Documentation is important to us, as bridges are complex beasts and rely on good documentation for both
administrators and users. There are a couple of things to keep in mind when when writing documentation
for bridge projects:</p>
<ul>
<li>Use <a href="https://en.wikipedia.org/wiki/Plain_English">Plain English</a> when documenting. Assume a non-native speaker audience.</li>
<li>Please take care to proofread.</li>
<li>Documentation should be written for both end users of the bridge, as well as system administrators. It should always be
made clear in the text which class of user you are targeting.</li>
</ul>
<h2 id="contributing-code"><a class="header" href="#contributing-code">Contributing code</a></h2>
<p>First of all, thank you for considering making a change to one of our projects. Every change no matter the size makes a difference! </p>
<h3 id="-code-style"><a class="header" href="#-code-style">🖌️ Code style</a></h3>
<p>Each repository contains an <code>eslint</code> configuration which will dictate the style of the code. All code should be written in
TypeScript. At time of writing, we target ES2020 (the latest version supported by Node 14). The CI will lint your code automatically,
but you can save yourself some time by running (<code>yarn lint</code>/<code>npm lint</code>) to check locally.</p>
<h3 id="-tests--ci"><a class="header" href="#-tests--ci">🧪 Tests / CI</a></h3>
<p>To test your changes, you can run the <code>test</code> command with either <code>yarn test</code> or <code>npm test</code>. Some projects may have additional
testing constraints noted in the project-specific section below.</p>
<p>Please be aware that reviewers will expect CI to be passing before your changes will be approved, and priority will be given to
PRs that pass CI when reviewing too. If you can't get the CI to pass, please reach out to us either via the PR or in the project
Matrix room (and do not assume that it's always your change that caused the test to fail!).</p>
<p><strong>As a rule, code does not get merged onto the <code>develop</code> branch without all CI tests passing.</strong></p>
<h3 id="tips-for-good-quality-submissions"><a class="header" href="#tips-for-good-quality-submissions">Tips for good quality submissions</a></h3>
<ul>
<li>When writing new features, remember to document them in the repository's chosen documentation system.</li>
<li>PRs should aim to be as constrained as possible: Do not attempt to solve multiple isolated issues in a single PR.
<ul>
<li>A good indication is that your changelog entry contains multiple statements. That usually means you need to consider splitting up your PR :)</li>
</ul>
</li>
<li>It's totally okay to submit draft PRs with the intention of getting feedback. Please use the GitHub comments feature to comment
on lines you would like assistance with.</li>
<li>Avoid writing TODOs / XXX comments in code. If you must, create an issue first with the details and link to it in the code.</li>
</ul>
<h3 id="-pull-requests"><a class="header" href="#-pull-requests">⬇️ Pull Requests</a></h3>
<p>When making a pull request, please ensure it [the PR] follows these best practises:</p>
<ul>
<li>
<p>Targets <code>develop</code> (unless it explicitly depends upon another feature, then depend on that branch and comment to that effect in the PR body).</p>
</li>
<li>
<p>Is updated via rebase mechanisms when <code>develop</code> changes, rather than merge commits (reduces noise).</p>
</li>
<li>
<p>Is <a href="https://matrix-org.github.io/synapse/latest/development/contributing_guide.html#sign-off">signed off</a>. Matrix.org projects require that the
sign off process has been followed in its entirety.</p>
</li>
<li>
<p>Has a <a href="https://matrix-org.github.io/synapse/latest/development/contributing_guide.html#changelog">changelog entry</a> in <code>changelog.d</code>.
A changelog filename should be <code>${GithubPRNumber}.{bugfix|misc|feature|doc|removal}</code>.
The change should include information that is useful to the user rather than the developer.</p>
<p>You can choose to sign your changelog entry to be credited by appending something like &quot;Thanks to @Half-Shot!&quot;
at the end of the file, on the same line.</p>
<p>You may be wondering how to determine your <code>GithubPRNumber</code> number ahead of time. <a href="https://matrix-org.github.io/synapse/latest/development/contributing_guide.html#how-do-i-know-what-to-call-the-changelog-file-before-i-create-the-pr">Synapse offers some useful
hints</a> for this.</p>
</li>
<li>
<p>Is passing CI. As noted above, please feel free to call out any CI issues you cannot fix.</p>
</li>
<li>
<p>Calls out any issue it may fix with a &quot;Fixes #issue-no&quot; in the body.</p>
</li>
</ul>
<p>When PRs are merged, we will squash the commits down to a single commit. Because of this, do not be afraid to
make multiple commits to a branch rather than amending and force pushing existing commits.</p>
<p>We aim to review all PRs in a timely manner, though be aware that larger PRs will take more thought.</p>
<h3 id="-review-process"><a class="header" href="#-review-process">✔️ Review process</a></h3>
<p>We aim to review all PRs from the community promptly, although we can't offer firm time commitments. If you think
your PR has been forgotten and it's been a while, do not hesitate to politely ping in the correct project room.</p>
<p>When reviewing a PR, a maintainer will:</p>
<ul>
<li>Constructively call out areas for improvement. Code reviews are as much about learning as getting code good,
so conversations always seek to improve <em>mutual</em> understanding.</li>
<li>Resolve a comment thread when they are satisfied. The author of the code may 👍 a review comment to say
they have acknowledged the message and will make the change.</li>
<li>Approve a PR which is ready to merge, or nearly ready with some minor tweaks or optional improvements.</li>
</ul>
<h2 id="-thats-it"><a class="header" href="#-thats-it">🏁 That's it!</a></h2>
<p>This guide aims to cover all bases to get new contributors started, but it won't be able to satisfy every question. If
you have any other questions, please seek us out in any of the project rooms and we will be happy to assist! Other than that,
thanks for taking the time to read this and improving our projects for
the benefit of all 😄</p>
<h2 id="hookshot"><a class="header" href="#hookshot">Hookshot</a></h2>
<p>Hi there! Please read the <a href="https://github.com/matrix-org/matrix-appservice-bridge/blob/develop/CONTRIBUTING.md">CONTRIBUTING.md</a> guide for all matrix.org bridge
projects.</p>
<h2 id="hookshot-guidelines"><a class="header" href="#hookshot-guidelines">Hookshot Guidelines</a></h2>
<ul>
<li>Hookshot presently uses the <code>main</code> branch as the default branch (instead of <code>develop</code>).</li>
<li>Since Hookshot caters to a range of services, we have additional tags such as <code>GitHub</code>, <code>GitLab</code>
which help us determine which services are affected by an issue.</li>
<li>In addition to Typescript, Hookshot makes use of <a href="https://rust-lang.org">Rust</a>. You will need to setup Rust in order to build the project. https://rustup.rs/ is a good option for most people.</li>
<li>The official hookshot support/development room is <a href="https://matrix.to/#/#hookshot:half-shot.uk">#hookshot:half-shot.uk</a></li>
</ul>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="troubleshooting.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<i class="fa fa-angle-left"></i>
</a>
<a rel="next" href="advanced/provisioning.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
<div style="clear: both"></div>
</nav>
</div>
</div>
<nav class="nav-wide-wrapper" aria-label="Page navigation">
<a rel="prev" href="troubleshooting.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<i class="fa fa-angle-left"></i>
</a>
<a rel="next" href="advanced/provisioning.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
</nav>
</div>
<script type="text/javascript">
window.playground_copyable = true;
</script>
<script src="elasticlunr.min.js" type="text/javascript" charset="utf-8"></script>
<script src="mark.min.js" type="text/javascript" charset="utf-8"></script>
<script src="searcher.js" type="text/javascript" charset="utf-8"></script>
<script src="clipboard.min.js" type="text/javascript" charset="utf-8"></script>
<script src="highlight.js" type="text/javascript" charset="utf-8"></script>
<script src="book.js" type="text/javascript" charset="utf-8"></script>
<!-- Custom JS scripts -->
<script type="text/javascript" src="docs/_site/main.js"></script>
<script type="text/javascript" src="docs/_site/version.js"></script>
</body>
</html>