🎉 Add Contributing Guide

This commit is contained in:
andy 2021-04-19 16:13:59 +02:00 committed by Andrés Moya
parent 520e13035a
commit 6236a6bc8e
18 changed files with 336 additions and 24 deletions

View File

@ -82,6 +82,7 @@
</ul>
<ul class="footer-block">
<li><a href="/user-guide">User guide</a></li>
<li><a href="/contributing-guide">Contributing guide</a></li>
<li><a href="/developer-guide">Developer guide</a></li>
<li><a href="/faqs">FAQs</a></li>
</ul>

View File

@ -0,0 +1,36 @@
---
layout: layouts/base.njk
templateClass: tmpl-contributing-guide
---
{%- macro show_children(item) -%}
{%- for child in item | children | sorted('data.title') %}
{%- if loop.first -%}<ul>{%- endif -%}
<li>
<a href="{{ child.url }}">{{ child.data.title }}</a>
{%- if page.url.includes(child.url) -%}
{{ show_children(child) }}
{%- endif -%}
{%- if child.url == page.url -%}
{{ content | toc(tags=['h2', 'h3']) | safe }}
{%- endif -%}
</li>
{%- if loop.last -%}</ul>{%- endif -%}
{%- endfor %}
{%- endmacro -%}
<div class="main-container with-sidebar">
<aside id="stickySidebar" class="sidebar">
{%- set root = '/contributing-guide/index' | find -%}
<div id="toc">
<div class="header mobile" id="toc-title">{{ root.data.title }}</div>
<a class="header" href="{{ root.url }}">{{ root.data.title }}</a>
{{ show_children(root) }}
</div>
</aside>
<content class="main-content">
{{ content | safe }}
</content>
</div>

View File

@ -0,0 +1,13 @@
---
title: 04· Code of Conduct
---
<h1 id="coc">Code of conduct</h1>
<p>As contributors and maintainers of this project, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.</p>
<p>We are committed to making participation in this project a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, or religion.</p>
<p>Examples of unacceptable behavior by participants include the use of sexual language or imagery, derogatory comments or personal attacks, trolling, public or private harassment, insults, or other unprofessional conduct.</p>
<p>Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct. Project maintainers who do not follow the Code of Conduct may be removed from the project team.</p>
<p>This code of conduct applies both within project spaces and in public spaces when an individual is representing the project or its community.</p>
<p>Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting one or more of the project maintainers.</p>
<p>This Code of Conduct is adapted from the Contributor Covenant, version 1.1.0, available from <a href="http://contributor-covenant.org/version/1/1/0/" target="_blank">http://contributor-covenant.org/version/1/1/0/</a></p>

View File

@ -0,0 +1,101 @@
---
title: 03· Core code contributions
---
<h1 id="code-contributions">Core code contributions</h1>
<p class="main-paragraph">Details to know how to improve Penpot's core code</p>
<h3 id="code-contributions-techguide">Technical guide</h3>
<p>Go to the <a href="/technical-guide">Technical guide</a> to get detailed explanations about how to get Penpot application and run it locally, to test it or make changes to it.</p>
<h3 id="code-contributions-pull-requests">Pull requests</h3>
<p>If you want propose a change or bug fix with the Pull-Request system firstly you should carefully read the <a href="#code-contributions-dco">DCO section</a> and format your commits accordingly.</p>
<p>If you intend to fix a bug it's fine to submit a pull request right away but we still recommend to file an issue detailing what you're fixing. This is helpful in case we don't accept that specific fix but want to keep track of the issue.</p>
<p>If you want to implement or start working in a new feature, please open a <b>question</b> / <b>discussion</b> issue for it. No pull-request will be accepted without previous chat about the changes, independently if it is a new feature, already planned feature or small quick win.</p>
<p>If is going to be your first pull request, You can learn how from <a href="https://app.egghead.io/playlists/how-to-contribute-to-an-open-source-project-on-github" target="_blank">this free video series</a>.</p>
<p>We will use the <code>easy fix</code> mark for tag for indicate issues that are easy for beginners.</p>
<h3 id="code-contributions-commits">Commit message guidelines</h3>
<p>We have very precise rules over how our git commit messages can be formatted.</p>
<p>The commit message format is:</p>
<pre>
<code>
&lt;type&gt; &lt;subject&gt;
[body]
[footer]
</pre>
</code>
<p>Where type is:</p>
<ul>
<li><g-emoji class="g-emoji" alias="bug" fallback-src="https://github.githubassets.com/images/icons/emoji/unicode/1f41b.png"><img class="emoji" alt="bug" height="20" width="20" src="https://github.githubassets.com/images/icons/emoji/unicode/1f41b.png"></g-emoji> <code>:bug:</code> a commit that fixes a bug</li>
<li><g-emoji class="g-emoji" alias="sparkles" fallback-src="https://github.githubassets.com/images/icons/emoji/unicode/2728.png"><img class="emoji" alt="sparkles" height="20" width="20" src="https://github.githubassets.com/images/icons/emoji/unicode/2728.png"></g-emoji> <code>:sparkles:</code> a commit that an improvement</li>
<li><g-emoji class="g-emoji" alias="tada" fallback-src="https://github.githubassets.com/images/icons/emoji/unicode/1f389.png"><img class="emoji" alt="tada" height="20" width="20" src="https://github.githubassets.com/images/icons/emoji/unicode/1f389.png"></g-emoji> <code>:tada:</code> a commit with new feature</li>
<li><g-emoji class="g-emoji" alias="recycle" fallback-src="https://github.githubassets.com/images/icons/emoji/unicode/267b.png"><img class="emoji" alt="recycle" height="20" width="20" src="https://github.githubassets.com/images/icons/emoji/unicode/267b.png"></g-emoji> <code>:recycle:</code> a commit that introduces a refactor</li>
<li><g-emoji class="g-emoji" alias="lipstick" fallback-src="https://github.githubassets.com/images/icons/emoji/unicode/1f484.png"><img class="emoji" alt="lipstick" height="20" width="20" src="https://github.githubassets.com/images/icons/emoji/unicode/1f484.png"></g-emoji> <code>:lipstick:</code> a commit with cosmetic changes</li>
<li><g-emoji class="g-emoji" alias="ambulance" fallback-src="https://github.githubassets.com/images/icons/emoji/unicode/1f691.png"><img class="emoji" alt="ambulance" height="20" width="20" src="https://github.githubassets.com/images/icons/emoji/unicode/1f691.png"></g-emoji> <code>:ambulance:</code> a commit that fixes critical bug</li>
<li><g-emoji class="g-emoji" alias="books" fallback-src="https://github.githubassets.com/images/icons/emoji/unicode/1f4da.png"><img class="emoji" alt="books" height="20" width="20" src="https://github.githubassets.com/images/icons/emoji/unicode/1f4da.png"></g-emoji> <code>:books:</code> a commit that improves or adds documentation</li>
<li><g-emoji class="g-emoji" alias="construction" fallback-src="https://github.githubassets.com/images/icons/emoji/unicode/1f6a7.png"><img class="emoji" alt="construction" height="20" width="20" src="https://github.githubassets.com/images/icons/emoji/unicode/1f6a7.png"></g-emoji> <code>:construction:</code>: a wip commit</li>
<li><g-emoji class="g-emoji" alias="construction_worker" fallback-src="https://github.githubassets.com/images/icons/emoji/unicode/1f477.png"><img class="emoji" alt="construction_worker" height="20" width="20" src="https://github.githubassets.com/images/icons/emoji/unicode/1f477.png"></g-emoji> <code>:construction_worker:</code> a commit with CI related stuff</li>
<li><g-emoji class="g-emoji" alias="boom" fallback-src="https://github.githubassets.com/images/icons/emoji/unicode/1f4a5.png"><img class="emoji" alt="boom" height="20" width="20" src="https://github.githubassets.com/images/icons/emoji/unicode/1f4a5.png"></g-emoji> <code>:boom:</code> a commit with breaking changes</li>
<li><g-emoji class="g-emoji" alias="wrench" fallback-src="https://github.githubassets.com/images/icons/emoji/unicode/1f527.png"><img class="emoji" alt="wrench" height="20" width="20" src="https://github.githubassets.com/images/icons/emoji/unicode/1f527.png"></g-emoji> <code>:wrench:</code> a commit for config updates</li>
<li><g-emoji class="g-emoji" alias="zap" fallback-src="https://github.githubassets.com/images/icons/emoji/unicode/26a1.png"><img class="emoji" alt="zap" height="20" width="20" src="https://github.githubassets.com/images/icons/emoji/unicode/26a1.png"></g-emoji> <code>:zap:</code> a commit with performance improvements</li>
<li><g-emoji class="g-emoji" alias="whale" fallback-src="https://github.githubassets.com/images/icons/emoji/unicode/1f433.png"><img class="emoji" alt="whale" height="20" width="20" src="https://github.githubassets.com/images/icons/emoji/unicode/1f433.png"></g-emoji> <code>:whale:</code> a commit for docker related stuff</li>
<li><g-emoji class="g-emoji" alias="rewind" fallback-src="https://github.githubassets.com/images/icons/emoji/unicode/23ea.png"><img class="emoji" alt="rewind" height="20" width="20" src="https://github.githubassets.com/images/icons/emoji/unicode/23ea.png"></g-emoji> <code>:rewind:</code> a commit that reverts changes</li>
<li><g-emoji class="g-emoji" alias="paperclip" fallback-src="https://github.githubassets.com/images/icons/emoji/unicode/1f4ce.png"><img class="emoji" alt="paperclip" height="20" width="20" src="https://github.githubassets.com/images/icons/emoji/unicode/1f4ce.png"></g-emoji> <code>:paperclip:</code> a commit with other not relevant changes</li>
<li><g-emoji class="g-emoji" alias="arrow_up" fallback-src="https://github.githubassets.com/images/icons/emoji/unicode/2b06.png"><img class="emoji" alt="arrow_up" height="20" width="20" src="https://github.githubassets.com/images/icons/emoji/unicode/2b06.png"></g-emoji> <code>:arrow_up:</code> a commit with dependencies updates</li>
</ul>
<p>More info:</p>
<ul>
<li><a href="https://gist.github.com/parmentf/035de27d6ed1dce0b36a">https://gist.github.com/parmentf/035de27d6ed1dce0b36a</a></li>
<li><a href="https://gist.github.com/rxaviers/7360908">https://gist.github.com/rxaviers/7360908</a></li>
</ul>
<p>The subject should be:</p>
<ul>
<li>Use the imperative mood.</li>
<li>Capitalize the first letter.</li>
<li>Don't put a period at the end of the subject line.</li>
<li>Put a blank line between the subject line and the body.</li>
</ul>
<h3 id="code-contributions-dco">Developer's Certificate of Origin (DCO)</h3>
<p>By submitting code you are agree and can certify the below:</p>
<pre>
<code>
Developer's Certificate of Origin 1.1
By making a contribution to this project, I certify that:
(a) The contribution was created in whole or in part by me and I
have the right to submit it under the open source license
indicated in the file; or
(b) The contribution is based upon previous work that, to the best
of my knowledge, is covered under an appropriate open source
license and I have the right under that license to submit that
work with modifications, whether created in whole or in part
by me, under the same open source license (unless I am
permitted to submit under a different license), as indicated
in the file; or
(c) The contribution was provided directly to me by some other
person who certified (a), (b) or (c) and I have not modified
it.
(d) I understand and agree that this project and the contribution
are public and that a record of the contribution (including all
personal information I submit with it, including my sign-off) is
maintained indefinitely and may be redistributed consistent with
this project or the open source license(s) involved.
</code>
</pre>
<p>Then, all your code patches (<b>documentation are excluded</b>) should contain a sign-off at the end of the patch/commit description body. It can be automatically added on adding <code>-s</code> parameter to <code>git commit</code>.</p>
<p>This is an example of the aspect of the line:</p>
<code>
Signed-off-by: Andrey Antukh <niwi@niwi.nz>
</code>
</pre>
<p>Please, use your real name (sorry, no pseudonyms or anonymous contributions are allowed).</p>

View File

@ -0,0 +1,4 @@
{
"layout": "layouts/contributing-guide.njk",
"tags": "contributing-guide"
}

View File

@ -0,0 +1,41 @@
---
title: Contributing
eleventyNavigation:
key: Contributing
order: 3
---
<div class="main-illus">
<img src="/img/home-contributing.png" alt="User guide" border="0">
</div>
<h1 id="contributing-guide">Contributing guide.</h1>
<p class="main-paragraph">In this documentation you will find (almost) everything you need to know about how to contribute at Penpot.</p>
<ul class="intro-sections">
<li>
<a href="/contributing-guide/reporting-bugs">
<h3>Reporting bugs</h3>
<p>Easy steps to bug hunting</p>
</a>
</li>
<li>
<a href="/contributing-guide/translations">
<h3>Translations</h3>
<p>How to become a Penpot translator</p>
</a>
</li>
<li>
<a href="/contributing-guide/code-contributions">
<h3>Core code contributions</h3>
<p>Help Penpot improve its code</p>
</a>
</li>
<li>
<a href="/contributing-guide/coc">
<h3>Code of conduct</h3>
<p>Rules, values and principles</p>
</a>
</li>
</ul>

View File

@ -0,0 +1,23 @@
---
title: 01· Reporting bugs
---
<h1 id="reporting-bugs">Reporting bugs</h1>
<p class="main-paragraph">Bug hunting is not difficult if you know how.</p>
<h3 id="reporting-bugs-howto">How to report a bug</h3>
<p>We are using <a href="https://github.com/penpot/penpot/issues" target="_blank">GitHub Issues</a> for our public bugs. We keep a close eye on this and try to make it clear when we have an internal fix in progress. Before filing a new task, try to make sure your problem doesn't already exist.</p>
<p>If you found a bug, please report it, as far as possible including:</p>
<ul>
<li>a detailed explanation of steps to reproduce the error.</li>
<li>a browser and the browser version used.</li>
<li>a dev tools console exception stack trace (if it is available).</li>
</ul>
<p>If you found a bug that you' woul'd rather discuss in private (for example: security bugs), consider first send an email to <a href="mailto:info@penpot.app">info@penpot.app</a>.</p>
<p><strong>We don't have formal bug bounty program for security reports; this is an open source application and your contribution will be recognized in the changelog.</strong></p>

View File

@ -0,0 +1,58 @@
---
title: 02· Translations
---
<h1 id="translations">Translations</h1>
<p class="main-paragraph">Thank you for interest in contribute translating Penpot. Here you will find ways to do it.</p>
<h3 id="translations-howto">How to become a Penpot translator</h3>
<p>We are using <a href="https://weblate.org/" target="_blank">Weblate</a> as translation platform, so the first thing you need to be a Penpot translator is to have a Weblate account (you can <a href="https://hosted.weblate.org/accounts/register/" target="_blank">register here</a>).</p>
<p>To start translating at Penpot:</p>
<ol>
<li>Open a <a href="https://github.com/penpot/penpot/issues" target="_blank">github issue</a> giving details about the language you want to translate (language), the type of translation (new language, new translation or change an existing translation) and your Weblate user.</li>
<li>If everything is correct we will get back to you providing you permissions to the actions needed.</li>
<li>You also might want to take a look at the guide for <a href="https://docs.weblate.org/en/latest/user/translating.html" target="_blank">Translating using Weblate</a>.</li>
</ol>
<h3 id="translations-howto">Add a new language</h3>
<p>To add a language that is still not among the Penpot language options:</p>
<ol>
<li>Go to the <a href="https://hosted.weblate.org/projects/penpot/frontend/" target="_blank">languages list</a>.</li>
<li>Press the "Start new translation" button.</li>
<li>Choose the language you want to translate to.</li>
<li>Press the "Start new translation" button at the start new translation page.</li>
<li>Start translating strings for the new language :)</li>
</ol>
<p><img src="/img/translations-start.png" alt="translations" /></p>
<p><img src="/img/translations-start-translation.png" alt="translations" /></p>
<h3 id="translations-howto">Add a new translation</h3>
<p>To add a new translation (a string with a lacking translation for a certain language) follow the next steps:</p>
<ol>
<li>Go to the <a href="https://hosted.weblate.org/projects/penpot/frontend/" target="_blank">languages list</a>.</li>
<li>Click the edit button (pencil icon) close to the name of the language where you want to add the missing translation or translations.</li>
<li>Find and select the translation/s to complete.</li>
<li>Complete the translation in the required input field.</li>
<li>Press the "Save· button.</li>
<li>Repeat the action with as many translation strings you can / you want ;)</li>
</ol>
<p>Saved new translations will automatically get the status "waiting for review". Our team will periodically check strings waiting for review and, if considered correct, will approve them.</p>
<p><img src="/img/translations-lang-list.png" alt="translations" /></p>
<p><img src="/img/translations-strings-list.png" alt="translations" /></p>
<h3 id="translations-howto">Change an approved translation</h3>
<p>To edit an already approved translation string follow the next steps:</p>
<ol>
<li>Go to the <a href="https://hosted.weblate.org/projects/penpot/frontend/" target="_blank">languages list</a>.</li>
<li>Click the name of the language where is the translation you want to change.</li>
<li>Click the Browse button.</li>
<li>Find and select the translation/s to complete.</li>
<li>Change the translation in the input field.</li>
<li>Press the "Save" button if you have permissions.</li>
<li>If you don't have permissions to Save you can still press "Suggest" to make a suggestion.</li>
</ol>
<p>Saved editions will get the status "Waiting for review". Suggestions will get the status "Approved strings with suggestions". Our team will periodically check strings waiting for review and, if considered correct, will approve them.</p>
<p><img src="/img/translations-lang-state.png" alt="translations" /></p>

View File

@ -656,6 +656,9 @@ a[href].direct-link:focus:visited,
.help-sections .illus-techguide {
background-image: url(/img/home-techguide.png);
}
.help-sections .illus-contributing {
background-image: url(/img/home-contributing.png);
}
.help-sections .illus-contact {
background-image: url(/img/home-contact.png);
}
@ -698,6 +701,7 @@ a[href].direct-link:focus:visited,
border-radius: 0;
box-shadow: none;
border-top: 1px dashed var(--graylight);
border-bottom: 1px dashed var(--graylight);
margin-top: 4rem;
}
.help-sections > li.github a:hover h3 {
@ -719,6 +723,19 @@ a[href].direct-link:focus:visited,
width: 72px;
height: 72px;
}
.contact-block {
text-align: center;
padding-top: 12rem;
margin-bottom: 6rem;
background-size: auto 75%;
background-position: center top;
background-repeat: no-repeat;
background-image: url(/img/home-contact.png);
}
.contact-block p,
.contact-block h3 {
max-width: initial;
}
.main-container h1 {
margin-top: 0rem;
@ -804,6 +821,32 @@ table tr:nth-child(odd) {
.header-title {
display: none;
}
header {
padding: 1rem;
position: relative;
}
header .nav-item:first-child {
display: none;
}
.header-inner {
display: block;
}
.search {
position: relative;
width: 100%;
margin-top: 2rem;
}
.search input {
width: 100%;
font-size: 1rem;
}
.search input:focus {
/* width: calc(100vw - 1.4rem); */
width: 100%;
}
.search input:focus + .search-icon {
display: none;
}
.preheader {
padding: 1rem;
}
@ -857,6 +900,7 @@ table tr:nth-child(odd) {
margin-top: 0;
max-width: none;
z-index: 2;
padding-right: 0;
}
.main-container.with-sidebar .sidebar #toc > ul {
background: white;
@ -898,28 +942,11 @@ table tr:nth-child(odd) {
padding-top: 1.4rem;
font-size: 1.4rem;
}
header {
padding: 1rem;
position: relative;
}
header .nav-item {
margin-left: 0.6rem;
margin-right: 0.6rem;
font-size: 1rem;
}
.search {
top: -0.3rem;
}
.search input {
width: 2rem;
padding: 0.5rem;
}
.search input:focus {
width: calc(100vw - 1.4rem);
}
.search input:focus + .search-icon {
display: none;
}
.main-container.with-sidebar .sidebar #toc {
padding: 0;
margin: 0;

View File

@ -3,7 +3,7 @@ title: FAQs
layout: layouts/faqs.njk
eleventyNavigation:
key: FAQs
order: 4
order: 5
---
<div class="main-illus">

BIN
img/home-contributing.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 57 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 77 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 73 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 55 KiB

BIN
img/translations-start.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 80 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 163 KiB

View File

@ -30,13 +30,16 @@ eleventyNavigation:
<p>Installation, configuration and architecture.</p>
</a>
</li>
<li class="illus illus-contact no-link">
<!-- a href="" -->
<li class="illus illus-contributing">
<a href="/contributing-guide/">
<h3>Contributing guide →</h3>
<p>How to report bugs, add translations and more.</p>
</a>
</li>
<!--li class="illus illus-contact no-link">
<h3>Contact us →</h3>
<p>Write us at <a href="mailto:info@penpot.app" target="_blank">info@penpot.app</a> or join the <a href="https://github.com/penpot/penpot/discussions" target="_blank">team discusions</a>.</p>
<!-- p>Write us an email, join team discussions or chat with us.</p-->
<!-- /a -->
</li>
</li-->
<li class="github">
<a href="https://github.com/penpot/">
<svg width="357.782" height="349.03" viewBox="0 0 335.421 327.216">
@ -49,3 +52,8 @@ eleventyNavigation:
</a>
</li>
</ul>
<div class="contact-block">
<h3>Contact us</h3>
<p>Write us at <a href="mailto:info@penpot.app" target="_blank">info@penpot.app</a> or join the <a href="https://github.com/penpot/penpot/discussions" target="_blank">team discusions</a>.</p>
</div>

View File

@ -9,7 +9,7 @@ eleventyNavigation:
<img src="/img/home-userguide.png" alt="User guide" border="0">
</div>
<h1 id="user-guide">Welcome to the Penpot user guide.</h1>
<h1 id="user-guide">Penpot user guide.</h1>
<p class="main-paragraph">In this documentation you will find (almost) everything you need to know about how to work with Penpot. From the interface basics to advanced functionality. Know details about topics such as prototyping, organizing your designs, or sharing to make a difference getting the best of Penpot.</p>