Move contribution guides to the documentation (#41)

Move contribution guides to the documentation
This commit is contained in:
Baptiste Gelez 2019-05-31 11:36:17 +01:00 committed by GitHub
commit a7fccd79bc
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
18 changed files with 363 additions and 2 deletions

View file

@ -0,0 +1,23 @@
---
title: Report a bug
summary: 'Somehting seems wrong? Maybe we can fix it together.'
icon: alert-triangle
time: 5 minutes
---
Plume is probably not perfect, and may contain bugs. If you see something that seems
abnormal (unexpected behavior, display issue, a grammar mistake, etc), you can report it, so that we can fix it.
## If you have a GitHub account
If the issue is about Plume itself, go on [this page](https://github.com/Plume-org/Plume/issues/new?assignees=&labels=C%3A+Bug&template=bug_report.md&title=).
Then, all you have to do is to fill the title and the description of your issue, and to validate.
If your issue isn't about Plume itself, find the appropriate repository [in the list](https://github.com/Plume-org), go to the "Issues"
tab, click the green "New issue" button, and describe your problem.
## If you don't have a GitHub account
If you don't have a GitHub account, and don't want to create one, you can also report your issue on Matrix.
Join the Plume room as explained in [this guide](/contribute/discussion), and send a message explaining what is wrong.
We will take care of creating an issue on GitHub for you.

View file

@ -0,0 +1,57 @@
---
title: Review the proposed changes
icon: git-pull-request
summary: 'Review one of the proposed pull requests.'
time: 30 minutes
---
Some people contribute to Plume by improving it's source code. They propose changes to the
software throught what is called "pull requests" on GitHub (thus you will need to create a GitHub
account to follow this guide, if you don't have one yet).
Here is the [list of all pull requests needing to be reviewed](https://github.com/Plume-org/Plume/pulls?q=is%3Apr+is%3Aopen+sort%3Aupdated-desc+review%3Arequired+label%3A%22S%3A+Ready+for+review%22).
Choose one that seems interesting to you, read the discussion for context about what needs to be reviewed,
and what was already tested, and start your review.
## Test the changes
Each pull request is deployed in live so that you can easily test the changes they bring.
The URL to access the test instance is `https://pr-XXX.joinplu.me/`, where `XXX` is the number
of the pull request (that is shown next to the title on GitHub).
A list of all running test instances is also available on [pr-list.joinplu.me](https://joinplu.me). Only
five instances may run at the same time, to avoid to overload our server. If the instance you wanted to access
is not available, wait for the CI to run again (it will restart it), choose another pull request, or test it locally
if you know how to do it.
A good start is to go to the test instance for your pull request, and to see if everything works as expected,
but also to try to find some corner cases that were not expected, and that may break something.
Don't hesitate to try the feature on different devices too, and from different browser, especially if it changes
the user interface.
## Review the code
If you know one of the programming languages used in Plume (Rust, SCSS, HTML and SQL mostly), you can also review the quality
of the code: give advices about it's efficiency, ask for clarification if you are not sure what it does, point out potential
bugs, etc.
You can do that by going to the "Files changed" tab on the page of pull request on GitHub. Then you will be able to comment on the
diff, as seen in this GIF:
![Commenting on the diff](/images/code-review.gif)
## Writing your review
Once you tested the changes, you need to tell to the person who proposed the pull request what you found.
The best way to do that is to go to the "Files changed" tabs on the GitHub pull request, and to click the green "Review
changes" button, in the top right corner. Then write a comment in the box that appears, explaining what worked, and what went
wrong. Don't hesitate to give precise information, explaining how to reproduce issues for instance. When making comments
about someone else's work, be kind, and try to make constructive critics.
Then click one of "Request changes", "Comment" or "Approve" to send your comments.
It is possible that the person who opened the pull request asks for more details: the review doesn't really
stop until the pull request is fully accepted (but you have the right to tell them you don't want to help with
review anymore, someone else will probably take care of it).

View file

@ -3,9 +3,24 @@ title: Development Guide
icon: git-merge
summary: 'How to install Plume on your computer and make changes to the source code.
This guide also gives you tips for making debugging and testing easier.'
priority: 2
time: 30 minutes
---
Plume is mostly made in Rust. The back-end uses Rocket and Diesel. The front-end
is in Rust too, thanks to WebAssembly. The stylesheets are written in SCSS.
If you want to write some code but you don't really know where to start, you
can try to find [an issue that interests you](https://github.com/Plume-org/Plume/issues).
Then, fork Plume (if you didn't already do it), `git clone` your fork, and start a
new branch with `git checkout -b NAME-OF-THE-BRANCH`. You can now start to work on the
issue.
Once you have something working, do `git add FILES THAT YOU CHANGED` (or `git add .` to add them all),
and then `git commit`. Write a message explaining your changes, and do `git push origin NAME-OF-THE-BRANCH`
to upload your work to GitHub. Open the URL that appears in the output of this last command to open
a pull request, that we will then review, and eventually merge.
## Installing the development environment
Please refer to the [installation guide](/installation). Choose to compile Plume

View file

@ -0,0 +1,34 @@
---
title: Join the discussion
icon: users
summary: 'Join our Matrix room, or our Loomio to take part to discussions about Plume, share your feedback, or ask for help.'
time: 10 minutes
---
Discussion about Plume mostly take place on two websites: Loomio (long posts, more like a forum with decision tools) and Matrix
(instant chat, more suited for support or feedback).
Most of the discussions are in English, but if you are not fluent enough, you can speak in another language your are more comfortable
with, maybe we speak it too, and even if we don't we will find ways to talk with you, don't worry!
## Joining the Matrix room
Matrix is federated chat (but it doesn't use ActivityPub 😛). If you don't have an account yet, you
can find an instance [here](https://www.hello-matrix.net/public_servers.php) (if you don't know which one to choose, just go for matrix.org).
Once you created an account, open [this link to join `#plume:disroot.org`](https://riot.im/app/#/room/#plume:disroot.org). And you are done!
This place is the best one to give feedback or to ask for help if you encounter issues while using Plume, or while contributing for example.
## Joining the Loomio
Our Loomio group is hosted [on Framavox](https://framavox.org/g/WK40YHMA/plume).
You will only be asked an email address to join it. Then, you will be able to comment
on discussion, open new topics and vote. Feel free to take part in any topic that seems interesting.
All the features that need the input from the whole community are discussed here.
## Giving us feedback
If you want to give us feedback about Plume, the best place is the Matrix room (you can do it in other places, but it is more likely to be missed).
Don't hesistate to be honest when giving us feedback, and to speak about negative points as well as positive ones. As long as you aren't rude we will
be happy to ear what you have to say about Plume.

View file

@ -0,0 +1,61 @@
---
title: Improve the documentation
icon: book-open
summary: 'Write new articles, review the current ones'
time: 30 minutes
---
Having an accurate, understandable and complete documentation is important.
Our documentation is [hosted on GitHub](https://github.com/Plume-org/docs), so you
will need an account here if you want to edit it. You will probably need to fork it
to create a temporary copy you have the right to edit (with the button in the top right corner).
## Documenting something new
If you want to start a new page from scratch, you can do it by going in the `source` folder (and eventually in
another of the sub-folders) and by clicking the "Create new file" button (at the top of the file list).
Enter its name: use a concise version of the title, with hyphens as separators between words, and the `html.md` extension.
Then you can start writing it, using [MarkDown](https://commonmark.org/help/). Documentation should be written in English.
At the top of your file, you can add some meta-data, like that:
```md
---
title: 'The title of the page'
summary: 'A summary of what is explained on this page.'
icon: icon-name
---
```
You can find a list of the icons you can use on [this page](https://feathericons.com/).
## Improving the current documentation
Our current documentation is probably not perfect, and proof-reading it helps a lot! However please note
this part only applies to the English documentation, if you want to improve the documentation in another language,
see how to [translate it](/contribute/translations).
To fix the mistakes you found, you will need to fork the documentation on GitHub (as explained in the first
paragraph of the previous part).
Once it's done, choose the page you want to review, and find the corresponding file on GitHub (the URL of the page in
the documentation and the name of the files are normally the same). Read the page to see if you can find typos, grammar
mistakes, sentences that can be improved, etc. If you see anything that could be improved, go to GitHub and edit the file.
## Saving your work and proposing your changes
Once you finished, you can save your work. To do that, GitHub asks you to make a short summary of your changes.
![The box to write a summary of your changes](/images/new-docs-page.png)
Once you saved your new file, you will have to propose us the changes. To do that you will have to create a new
pull request, that is a space where we can discuss your changes if needed, and then accept them. To do that, use the
"Pull request" button in the file list.
![The button to create a new pull request](/images/docs-pr-button.png)
You can normally leave the default settings (optionally edit the title and the description if you want),
and hit the "Create pull request" button.

View file

@ -0,0 +1,14 @@
---
title: 'Make a donation'
icon: dollar-sign
summary: 'Support Plume financially.'
time: 10 minutes
---
Plume is present [on Liberapay](https://liberapay.com/Plume). All you have to do
to make us a donation, is to register on Liberapay and to configure a payment method,
and then to click the "Donate" button on our page. Then just follow the instructions.
It is not clear how Liberapay works since the incident they had in July 2018. However, you
can be sure that any amount you give to Plume will be received by the contributors.

View file

@ -0,0 +1,24 @@
---
title: Request a feature
icon: edit
summary: 'You have an idea of improvements for Plume? Let us know!'
time: 10 minutes
---
If you have an idea for a new feature in Plume, we will be happy to ear what
you have to propose.
## It may need to be discussed
If your feature is controversial, or not totally clear yet, the best is to open a new discussion
[on Loomio](https://framavox.org/g/WK40YHMA/plume). If you are not sure how to do that, we have
[a guide about it](/contribute/discussion). Give as much details as possible. Especially, explain
which problem you are trying to solve with this new feature.
## It doesn't really need to be discussed
Then you can open [an issue on GitHub](https://github.com/Plume-org/Plume/issues/new?assignees=&labels=&template=feature_request.md&title=),
if you have an account there. Just fill the information asked in the form, and click "Submit new issue".
If you don't have a GitHub account, you can also suggest your feature in [the Matrix room](/contribute/discussion), and we
will create the issue for you.

View file

@ -0,0 +1,44 @@
---
title: Contribute to Plume
summary: "You want to help, but you don't know how? These guides explain you how to translate Plume, hack on its source code, write documentation, etc."
icon: heart
priority: 2
---
<p><b>Before contributing, be sure to read and agree with our <a href="/organization/code-of-conduct">Code of conduct</a></b></p>
<p>Here is a (non-exhaustive) list of how you can contribute to Plume. Some may suit you better, depending on your skills and the time you want to offer to the project</p>
<div class="cards">
<% sitemap.resources
.select{ |p| p.path =~ /\.html/ && p.path != "index.html" && p.url.chomp('/').split('/').size == 3 && p.path =~ /contribute\// }
.sort{ |a, b| a.data.title <=> b.data.title }
.sort{ |a, b| -(a.data.priority || 0) <=> -(b.data.priority || 0) }
.each do |res|
%>
<article>
<i data-feather="<%= res.data.icon %>"></i>
<h2>
<a href="<%= res.url %>"><%= res.data.title %></a>
</h2>
<p><%= res.data.summary %></p>
<% if res.data.time %>
<small>Minimum time: <%= res.data.time %></small>
<% end %>
</article>
<% end %>
</div>
<p>But you can also contribute differently. For instance, you could:</p>
<ul>
<li>Talk about the project (super easy, and super helpful)</li>
<li>Write articles on Plume</li>
<li><a href="/installation">Open your own instance</a></li>
<li>Make a security audit</li>
<li>Integrate Plume with other projects. For instance you could use the <a href="/API">API</a> to make it possible to publish on Plume from your favorite writing app</li>
</ul>
<p>If you contributed to Plume, you can add yourself to the <a href="/organization/contributors">contributors page</a> if you want.</p>
<p>If you ever encounter some difficulties while trying to contribute, please <a href="/contribute/discussion">tell us</a>, we will be happy to help you.</p>

View file

@ -0,0 +1,75 @@
---
title: Translators Guide
icon: message-circle
summary: 'Explains how to translate Plume, joinplu.me and this documentation'
time: 10 minutes
---
We use [Crowdin](https://crowdin.com) to translate Plume, the joinplu.me website and the documentation.
All the original text are in English, so you will need to understand it, and to be fluent in another
language to help us with translation.
## Create a Crowdin account
To translate Plume and the related projects, the first step is thus to create a Crowdin account (unless
you already have one).
You can register [here](https://crowdin.com/join). It will just ask you the typical registration information.
You can also sign in with an account from other platforms if you want (GitHub for instance).
## Join one of the Plume projects
All the strings that need to be translated can be found in one of these projects:
- [Plume](https://crowdin.com/project/plume): the Plume interface itself.
- [Plume Documentation](https://crowdin.com/project/plume-docs): the documentation you are currently reading.
- [Joinplu.me](https://crowdin.com/project/joinplume): the website introducing Plume.
One these pages, you will find a list of languages. Select the one you want to translate.
![The list of all currently available languages](/images/language-list.png)
If your language is not in the list, [tell us](/contribute/discussion), we will add it.
Once you selected a language, you will see a list of files to translate. Find one that is not
100% complete, and open it. Something like that should load:
![The Crowdin editor](/images/crowdin-editor.png)
Let's see what we have here.
![The Crowdin editor, but with colors for the different areas](/images/crowdin-editor-area.png)
- In yellow (left sidebar), you have the list of strings to translate. Those with a green square
are already translated, those with a red one are still to be done.
- In blue (middle-top area), you have the actual editor, with on the top the original string, and under
it, the box where you write translations. Sometimes, some context will be given next to the original string.
And there is a button to save your translations too (you can do `Ctrl`/`⌘`+`Enter` to save without leaving your keyboard too).
- In red (middle-bottom area), you have previous suggestions made by other people, and translations suggested by
various translation services. They can sometimes be helpful, but most of the time, nothing is better than human translations.
- And finally, in purple (right sidebar), you have an area where you can leave comments or ask questions. For instance, if
you need more context about a string, you can ask here. We will try to answer you as fast as possible, but we are not working
full-time on Plume, so don't worry if you don't get a reply in 5 minutes.
## In-context translations
Crowdin also provides a quite useful tool, called "in-context translations".
It allows you to translate website, while browsing them, and thus having all the context to understand what needs to be done.
We installed this tool for the documentation and joinplu.me (we may install it for Plume too one day, but it is a bit more
complicated). You can go on [translate.docs.joinplu.me](https://translate.docs.joinplu.me/) and [translate.joinplu.me](https://translate.joinplu.me/)
to use it.
![An example of in-context translation](/images/crowdin-in-context.png)
## Recommendations
When translating Plume (and related projects), please try to follow these rules:
- Be as inclusive as possible: if your langage has a form of inclusive writing, use it.
The style of inclusive that is choosen is not very important (just try to keep coherent with what is already done).
- Don't be too formal (but stay polite!).
---
That's it, you know everything you need to translate Plume! Thank you for your help!

Binary file not shown.

After

Width:  |  Height:  |  Size: 390 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 134 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 118 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 129 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 11 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 59 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 29 KiB

View file

@ -20,4 +20,4 @@ show_links: yes
<p><%= res.data.summary %></p>
</article>
<% end %>
</div>
</div>

View file

@ -191,6 +191,20 @@ aside {
main > article {
padding: 3em 0em;
img {
max-width: 90%;
display: block;
margin: 2em auto;
}
hr {
margin: 4em auto;
border: none;
background: $black;
height: 1px;
max-width: 5em;
}
}
main > article > * {