Edit learn.robosats.com "Contribute" Documentation (#587)

* Update 00-contribute.md

Add context to body

* Update 01-development.md

Add context, revise typos and grammatical error

* Update 02-languages.md

Add context, correct typos and grammatical errors

* Update 03-liquidity.md

Add rough draft for opening channels, and how that can be a way to contribute to RoboSats

* Update 04-guides.md

Add rough draft for contributing guides, and general things to consider

* Update 05-art.md

Add rough draft for art

* Update 06-outreach.md

Add rough draft for outreach

* Update 07-donate.md

Fix typos

* Update 01-development.md

Revise wording

* Update 03-liquidity.md

Revise wording

* Update 06-outreach.md

Revise wording
This commit is contained in:
okada-blue 2023-05-16 10:40:17 +00:00 committed by GitHub
parent 73eb4df291
commit b4a54f3b1a
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
8 changed files with 119 additions and 53 deletions

View File

@ -8,7 +8,9 @@ sidebar:
src: "_pages/contribute/00-contribute.md"
---
RoboSats is a fully community driven project. You can help RoboSats get better in many different ways.
RoboSats is a fully open source project and, as such, a community-driven effort! You can help RoboSats improve in many different ways (you don't even need to know how to code). Help by translating, creating guides, simply telling others to use RoboSats, and more!
Check them out:
1. [Development](/contribute/code/)
2. [Translations](/contribute/languages/)
@ -18,4 +20,4 @@ RoboSats is a fully community driven project. You can help RoboSats get better i
6. [Tell someone](/contribute/outreach/)
7. [Donate](/contribute/donate/)
{% include wip %}
{% include improve %}

View File

@ -10,30 +10,29 @@ toc_sticky: true
src: "_pages/contribute/01-development.md"
---
Everyone can contribute to the development of the Robotic Satoshis Open Source Project. If you're looking for somewhere to start contributing, check out the [good first issue](https://github.com/RoboSats/robosats/issues?q=is%3Aopen+is%3Aissue+label%3A"good+first+issue") list.
Everyone can contribute to the development of the Robotic Satoshis (RoboSats) open source project. If you're looking for somewhere to start contributing, then check out the issue list sharing the ["good first issue"](https://github.com/RoboSats/robosats/issues?q=is%3Aopen+is%3Aissue+label%3A"good+first+issue") label; such issues are good for newcomers.
This contributing guide is based on the [Bisq contributing guide](https://github.com/bisq-network/bisq/blob/master/CONTRIBUTING.md). While the scope and complexity of RoboSats is more manageable, following best practices is free.
This contributing guide is based on the [Bisq contributing guide](https://github.com/bisq-network/bisq/blob/master/CONTRIBUTING.md). Following best FOSS practices helps development remain organized as the project grows with new features and is continually optimized. Future contibutors will thank you for following these best practices and making your work easier to build on!
## Communication Channels
- **Matrix:** [RoboSats Development](https://matrix.to/#/#robosats:matrix.org) - Our main developer communcation chat
- **Matrix:** [RoboSats Development Group](https://matrix.to/#/#robosats:matrix.org). Main developer communication group chat.
- **Telegram:**
Most general communication about RoboSats happens on the main Telegram group. However, public community driven support is available in other languages.
* EN [t.me/robosats](https://t.me/robosats) (main)
* ES [t.me/robosats_es](https://t.me/robosats_es)
* RU [t.me/robosats_ru](https://t.me/robosats_ru)
* PT [t.me/robosats_pt](https://t.me/robosats_pt)
* CN [t.me/robosats_cn](https://t.me/robosats_cn)
- **Telegram:** [RoboSats Main Group EN🇬🇧](https://t.me/robosats). General discussion about RoboSats and any community-driven support happens publicly in the main Telegram group (English). If you're wanting to hang out with other cool robots and/or have questions about RoboSats, then those discussions happen in Telegram. There are more groups available for public, community-driven support in other languages:
- ES🇪🇸 [t.me/robosats_es](https://t.me/robosats_es)
- RU🇷🇺 [t.me/robosats_ru](https://t.me/robosats_ru)
- PT🇵🇹 [t.me/robosats_pt](https://t.me/robosats_pt)
- CN🇨🇳 [t.me/robosats_cn](https://t.me/robosats_cn)
Discussion about code changes happens in GitHub issues and pull requests.
- **Twitter:** [RoboSats](https://twitter.com/RoboSats). Provides important project updates, tips and tricks of using RoboSats, and other privacy-centric commentary. Questions may be asked to the Twitter account; however, Twitter limits the number of characters in a tweet and makes responding to questions restrictive. It's best to direct your questions to the aforementioned public Telegram support group for a faster and more detailed response from community members!
- **Nostr:** [npub1p2psats79rypr8lpnl9t5qdekfp700x660qsgw284xvq4s09lqrqqk3m82](https://snort.social/p/npub1p2psats79rypr8lpnl9t5qdekfp700x660qsgw284xvq4s09lqrqqk3m82). Relays Twitter tweets and similarly responds to questions. While character limit is no issue, it's still best to direct your questions to the aforementioned public Telegram support group for a faster response from community members!
Discussion about code changes happens in GitHub issues and pull requests (PRs).
## Contributor Workflow
All RoboSats contributors submit changes via pull requests. The workflow is as follows:
- Fork the repository
- Create a topic branch from the `main` branch
- Commit patches
@ -43,13 +42,11 @@ All RoboSats contributors submit changes via pull requests. The workflow is as f
Pull requests should be focused on a single change. Do not mix, for example, refactorings with a bug fix or implementation of a new feature. This practice makes it easier for fellow contributors to review each pull request.
## Reviewing Pull Requests
Robosats follows the review workflow established by the Bitcoin Core project. The following is adapted from the [Bitcoin Core contributor documentation](https://github.com/bitcoin/bitcoin/blob/master/CONTRIBUTING.md#peer-review):
Anyone may participate in peer review which is expressed by comments in the pull request. Typically reviewers will review the code for obvious errors, as well as test out the patch set and opine on the technical merits of the patch. Project maintainers take into account the peer review when determining if there is consensus to merge a pull request (remember that discussions may have been spread out over GitHub and Telegram). The following language is used within pull-request comments:
- `ACK` means "I have tested the code and I agree it should be merged";
- `NACK` means "I disagree this should be merged", and must be accompanied by sound technical justification. NACKs without accompanying reasoning may be disregarded;
- `utACK` means "I have not tested the code, but I have reviewed it and it looks OK, I agree it can be merged";
@ -62,15 +59,15 @@ Please note that Pull Requests marked `NACK` and/or GitHub's `Change requested`
[Check the current state of the Developer Compensated tasks in the Github Project](https://github.com/users/Reckless-Satoshi/projects/2/views/5)
At the moment RoboSats is a young and unfunded project. However, it has shown the ability to generate revenue, although it barely covers the running costs. A developer compensation program is the the best way to ensure the sustained support of the code base. For the time being, code contributions to the core project will be given small rewards: more akin to kudos than a meaningful monetary compensation. The pilot procedure for compensated development:
At the moment, RoboSats is a young and unfunded project, but has shown the ability to generate enough revenue to barely cover operational costs. A developer compensation program is the best way to ensure the sustained support of the code base. For the time being, code contributions to the core project will be given small rewards more akin to a tip than a meaningful monetary compensation. The pilot procedure for compensated development:
1. The developer opens a PR with the description of the work that will be done, optionally including the amount of Sats he thinks the work deserves.
2. An offer/negotiation takes place to set an amount of Sats until agreement. Everyone is welcome to express opinion on whether the compensation is right for the PR.
2. An offer/negotiation takes place to set an amount of Sats until agreed upon. Everyone is welcome to express opinion on whether the compensation is right for the PR.
3. The work happens: buidl, buidl, buidl!
4. The review takes place. Once maintainers give the OK for the merge...
5. The developer submits a LN invoice (with a long expiration time). The invoice is paid at merge.
5. The developer submits an LN invoice (with a long expiration time). The invoice is paid at merge.
Every step (negotiation, code submission, review and invoice submission) must take place publicly in GitHub (i.e., no private messaging). Please contact the team lead for development (@reckless-satoshi) upfront if you have doubts whether your contribution is suitable for compensation. Currently, only contributions to the frontend or backend core functionality and maintainence are eligible for compensations (that excludes, for the time being, art, translations, etc...).
Every step (negotiation, code submission, review and invoice submission) must take place publicly in GitHub (i.e., no private messaging and the like). Please contact the team lead for development (@reckless-satoshi) upfront if you have doubts whether your contribution is suitable for compensation. Currently, only contributions to the frontend or backend core functionality and maintainence are eligible for compensations (for the time being, that excludes: art, translations, etc.).
## Style and Coding Conventions
@ -90,7 +87,6 @@ From https://chris.beams.io/posts/git-commit/#seven-rules:
6. Wrap the body at 72 characters (*)
7. Use the body to explain what and why vs. how
### Sign your commits with GPG
See https://github.com/blog/2144-gpg-signature-verification for background and
@ -102,4 +98,4 @@ The [.editorconfig](.editorconfig) settings in this repository ensure consistent
### Keep the git history clean
It's very important to keep the git history clear, light and easily browsable. This means contributors must make sure their pull requests include only meaningful commits (if they are redundant or were added after a review, they should be removed) and _no merge commits_.
It's very important to keep the git history clear, light and easily browsable. This means contributors must make sure their pull requests include only meaningful commits (if they are redundant or were added after a review, they should be removed) and _no merge commits_.

View File

@ -11,44 +11,43 @@ src: "_pages/contribute/02-languages.md"
---
RoboSats is a way to exchange BTC for **any currency of the world**. As such, for many users this tool might only be useful if it is available in a language they can understand. Translating RoboSats into a new language is one of the most valuable contributions to the project, as it makes it available to new audience, increasing the reach of this cool freedom tool.
RoboSats is a way to exchange BTC for **any currency of the world**. As such, many users might only find this tool useful if it is available in a language they understand. Translating RoboSats into a new language is one of the most valuable contributions to the project! It makes the platform available to new audiences, increases the reach of this cool freedom tool, and subsequently increases order book liquidity for even more users to stack Sats privately.
There isn't a lot of text in RoboSats, however it might be best to split the work with another contributor. You can poll in the telegram community @RoboSats and find users willing to split the task.
There isn't a lot of text in RoboSats; however, it might be best to split the work with another contributor. You can reach out to the [Telegram communities](https://learn.robosats.com/contribute/code/#communication-channels) and find users willing to split the task.
### How to contribute a new translation.
## How To Contribute a New Translation
Simply create a new translation file in `frontend/src/static/locales` [Link to GitHub](https://github.com/RoboSats/robosats/tree/main/frontend/static/locales). In `locales` there is a single file with a json dictionary for every language. In order to create a new translation, simply copy `en.json` (the master text) into a new file named after the language's [ISO 639 two character code](https://www.loc.gov/standards/iso639-2/php/English_list.php).
Simply create a new translation file in `frontend/src/static/locales` [link to GitHub](https://github.com/RoboSats/robosats/tree/main/frontend/static/locales). In `locales` there is a single file with a json dictionary for every language. In order to create a new translation, simply copy `en.json` (the master text) into a new file named after the language's [ISO 639 two character code](https://www.loc.gov/standards/iso639-2/php/English_list.php).
### Guidelines
## Guidelines
Each language `.json` dictionary contains pairs of keys and values in the following format { "key1":"value1", "key2":"value2", ...}. Most keys are the literal English sentence. These simply have to be translated on the right side, for example, in order to translate the `Make Order` button to Spanish we edit the json file to look like this `{... "Make Order":"Crear Orden",...}`.
Each language `.json` dictionary contains pairs of keys and values in the following format { "key1":"value1", "key2":"value2", ...}. Most keys are the literal English sentence. These simply have to be translated on the right side, for example, in order to translate the `Make Order` button to Spanish, you would edit the json file to look like this `{... "Make Order":"Crear Orden",...}`.
#### 1. **Not all keys are explicit sentences.**
Some keys are not the English senstence but a variable names e.g. "phone_unsafe_alert". In this case you must take a look at the value originally in `en.json`.
### 1. **Not all keys are explicit sentences.**
Some keys are not the English sentence, but a variable name. E.g., "phone_unsafe_alert". In this case, you must take a look at the value originally in `en.json`.
#### 2. **The language dictionary is split into 9 sections.**
The first key of each section is a reference and does not need to be translated. For example, the second section starts with the key:value `"USER GENERATION PAGE - UserGenPage.js": "Landing Page and User Generation"` . It does not need to be translated, it is just information for the translator to understand what part of the app he will be working on.
### 2. **The language dictionary is split into 9 sections.**
The first key of each section is a reference and does not need to be translated. For example, the second section starts with the key:value `"USER GENERATION PAGE - UserGenPage.js": "Landing Page and User Generation"`. It does not need to be translated; it is just information for the translator to understand what part of the app they will be working on.
#### 3. **Try to keep a similar length to the original sentence.**
In most cases it will be okay if the translation is shorter. However, translations that result in a higher character count might break the UI! It might not always be possible to stick to the length of the English sentence. In those cases the UI might have to be changed, contact the responsible person for such a change.
### 3. **Try to keep a similar length to the original sentence.**
In most cases it will be okay if the translation is shorter. However, translations that result in a higher character count might break the UI! It might not always be possible to stick to the length of the English sentence. In those cases, the UI might have to be changed. Contact the person responsible for such a change.
#### 4. **Some sentences contain variables**
### 4. **Some sentences contain variables.**
For example, {{currencyCode}}. It will insert the currency code where the variable is found. E.g., `"Pay 30 {{currencyCode}}"` will render as "Pay 30 USD".
#### 5. **Some sentences contain HTML tags**
These tags are usually hyperlinks. For example in `{"phone_unsafe_alert": "Use <1>Tor Browser</1> and visit the <3>Onion</3> site."}` the children text of <1> (Tor Browser) will link to the Tor Download website, and the children of <3> will link to the RoboSats Onion site.
### 5. **Some sentences contain HTML tags.**
These tags are usually hyperlinks. For example, in `{"phone_unsafe_alert": "Use <1>Tor Browser</1> and visit the <3>Onion</3> site."}` the children text of <1> (Tor Browser) will link to the Tor Download website, and the children of <3> will link to the RoboSats Onion site.
#### 6. **It is best to translate from top to bottom of the .json file**
Some text is high priority, some other text is low priority.** Some keys are likely to change soon or they might not be so relevant for the user of the app. The translation files are sorted from top to bottom by the priority of the translation.
### 6. **It is best to translate from top to bottom of the .json file**
Some text is high priority, other text is low priority. Some keys are likely to change soon or they might not be so relevant for the user of the app. The translation files are sorted from top to bottom by the priority of the translation.
#### 7. Use a **spell checker**
Yes, please ;)
### 7. **Use a spell checker.**
Yes, please! 😉
#### 8. **Understand the context, where will this string be displayed?**
Literal translations might not work well in some languages. While in English the wording is always similar regardless of the position in the UI, in some languages it might be very different if you are translating a button (the user is taking an action) or if you are simply translating a tooltip. It might be clever to translate the strings while looking at the app. However, many strings can only be found while trading. The testnet RoboSats site is great for this use, as you can explore the whole app simply interacting with it with a testnet lightning wallet. However, if you cannot find where a string is displayed, it might be faster to simply write a message on the telegram group @robosats.
### 8. **Understand the context; where will this string be displayed?**
Literal translations might not work well in some languages. While in English the wording is always similar regardless of the position in the UI, in some languages it might be very different if you are translating a button (the user is taking an action) or if you are simply translating a tooltip. It might be clever to translate the strings while looking at the app. However, many strings can only be found while trading. The testnet RoboSats site is great for this use! You can explore the whole app by simply interacting with it using a testnet Lightning wallet. However, if you cannot find where a string is displayed, it might be faster to simply write a message on the [Telegram group](https://t.me/robosats).
#### 9. **Congratulate yourself**
### 9. **Congratulate yourself!!**
Seriously. It's so awesome you are helping build freedom tools!
{% include improve %}

View File

@ -5,7 +5,31 @@ permalink: /contribute/liquidity/
sidebar:
title: '<img id="side-icon-verybig" src="/assets/vector/circle-nodes.svg"/>LN liquidity'
nav: contribute
toc: true
toc_sticky: true
src: "_pages/contribute/03-liquidity.md"
---
{% include wip %}
One way to contribute to RoboSats is by opening a channel to the [RoboSats experimental coordinator node](https://amboss.space/node/0282eb467bc073833a039940392592bf10cf338a830ba4e392c1667d7697654c7e) and providing the node with outbound liquidity. Simply use the platform to sell bitcoin and push liquidity to RoboSats' end!
## RoboSats is Not a Routing Node
RoboSats is not a typical Lightning Network routing node. A node intended for routing payments wants balanced channels to maximize chance of successful payment forwarding. The RoboSats experimental coordinator node wants to maximize:
1. The amount of concurrent pending HTLCs without failure (bond/escrow).
2. The reliability of incoming payments being paid out to users, regardless of the channel.
With that being said, it doesn't matter if all of the outbound liquidity from the RoboSats experimental coordinator node is concentrated in two channels so long as when paying a buyer is necessary, connected nodes effectively route the payment. Liquidity concentration of a few channels is only an issue for poorly-connected nodes.
## Bitcoin Sellers Opening Channels
As an example, a seller creates a new node and their only channel is with the RoboSats experimental coordinator node. They push liquidity to RoboSats' end and, consequently, the RoboSats experimental coordinator node cannot use that same channel to deliver the Sats to the buyer. The channel is considered "dead end" liquidity.
It is for this reason that opening a channel to the RoboSats experimental coordinator node is only useful for the liquidity provider (seller) where they incur zero routing fees and have higher routing reliability. When a channel is completely saturated (and the seller cannot push liquidity anymore), it then gets closed and Sats are used to open outbound channels to a reliable peer.
## Bitcoin Buyers Opening Channels
As a buyer, opening channels is less useful. Doing so would only improve reliability. Keep in mind that by opening a direct channel with the RoboSats experimental coordinator node, all liquidity will be on your side! So, that channel would not be useful to receive a payout right away.
{% include improve %}

View File

@ -5,7 +5,26 @@ permalink: /contribute/guides/
sidebar:
title: '<img id="side-icon-verybig" src="/assets/vector/graduation-cap.svg"/>Guides'
nav: contribute
toc: true
toc_sticky: true
src: "_pages/contribute/04-guides.md"
---
{% include wip %}
While RoboSats strives to be a smooth and intuitive buying/selling experience, many users still prefer to rely on guides and tutorials for applications they've never used before! Help out by writing your own guide detailing your RoboSats experience!
Guides, tutorials, demos, etc. are invaluable additions to the RoboSats website. There are so many cool features of RoboSats that there can be generic guides (how to buy, sell, swap, etc.) and also many purpose-specific guides (how to use specific swap methods, receiving to on chain, receiving to wrapped invoice, etc.).
## Things To Consider
In order to provide your readers/viewers the most accurate information about the platform, consider briefly checking out the RoboSats documentation here on [learn.robosats.com](https://learn.robosats.com). There you will find many characteristics and aspects of RoboSats in fine detail, as well as some [previously created tutorials](https://learn.robosats.com/watch/en/) which may help serve as reference for your tutorial.
If you have lingering questions that are not answered in the documentation, then please do not hesitate to reach out and ask in the [public Telegram support groups](https://learn.robosats.com/contribute/code/#communication-channels).
If you are trying to do a live demonstration of RoboSats for a meetup or conference event, there are willing robot peers in the aforementioned Telegram groups who would be thrilled to lend a robotic hand! There is nothing cooler (and more helpful) for first-timers than seeing RoboSats live and in action!
## How To Add Your Guide Here
Once you create a guide, you can request to add it to the RoboSats documentation site! Simply create a pull request on the GitHub!
{% include improve %}

View File

@ -5,7 +5,18 @@ permalink: /contribute/art/
sidebar:
title: '<img id="side-icon-verybig" src="/assets/vector/palette.svg"/>Art'
nav: contribute
toc: true
toc_sticky: true
src: "_pages/contribute/05-art.md"
---
{% include wip %}
Got artistic talent? Consider drawing fan art and promoting RoboSats through sweet visuals! A picture is worth a thousand words, and also generates more engagement than longform articles. We aren't looking for Vincent van Gogh or Pablo Picasso, just excited individuals who like to draw and share the good word of buying/selling peer-to-peer!
## Ideas
There really is no limit here! If you want to brainstorm, feel free to message the [public Telegram support groups](https://learn.robosats.com/contribute/code/#communication-channels). The coordinator for RoboSats art is [Red_Purdy](https://twitter.com/Red_Purdy) and can help provide ideas!
One example of using art to create community engagement includes [Telegram stickers](https://t.me/addstickers/Robosats1). The linked stickers features the quasi mascot Robotoshi.
{% include improve %}

View File

@ -5,7 +5,22 @@ permalink: /contribute/outreach/
sidebar:
title: '<img id="side-icon-verybig" src="/assets/vector/bullhorn.svg"/>Outreach'
nav: contribute
toc: true
toc_sticky: true
src: "_pages/contribute/06-outreach.md"
---
{% include wip %}
The single best way to support RoboSats is by simply using it and telling others to try it out! Without peers providing liquidity to the order books, peer-to-peer exchanges like us would cease to exist! When peers use RoboSats and invite others to give it a try, liquidity grows and then the platform can support even more users!
The best we can do is reason with users of why they should value their privacy and avoid anti-privacy exchanges. Refer to this [article](https://bitcoinmagazine.com/culture/the-value-of-p2p-bitcoin-exchanges), written by a RoboSats contributor, explaining some of the reasons why users should consider protecting their privacy and using P2P exchanges like RoboSats.
## Social Media
Social media is a great opportunity for word-of-mouth advertising of RoboSats. If you had a great experience using RoboSats or have interesting insight to share about the project, please do say something! Shout it from the robo-heavens!
For example, you could create a tweet and tag the [RoboSats Twitter](https://twitter.com/RoboSats) account so that we can retweet it! Note that not all tweets are guaranteed retweets. Similarly, you could post on Nostr and tag RoboSats Nostr (npub1p2psats79rypr8lpnl9t5qdekfp700x660qsgw284xvq4s09lqrqqk3m82) account so that it can be shared with others.
Any help would be greatly appreciated in this sector! More order book liquidity attracts more users and thus more users get to take advantage of buying and selling bitcoin privately!
{% include improve %}

View File

@ -11,7 +11,7 @@ src: "_pages/contribute/07-donate.md"
We do not think RoboSats development should rely on donations in order to stay alive. The objective of the project is to generate enough revenue to cover for development, server, liquidity and promotional costs. The **best way to donate to RoboSats is to actively make use of the tool** and tell your friends.
We do, however, get approached by very enthusiastic bitcoiners who want to boots RoboSats' development and longevity further. We very much appreciate these donations, specially since the platform is still very young and still runs at net loss.
We do, however, get approached by very enthusiastic bitcoiners who want to boost RoboSats' development and longevity further. We very much appreciate these donations, especially since the platform is still very young and still runs at net loss.
You can donate the following ways:
@ -23,7 +23,7 @@ You can donate the following ways:
npub1p2psats79rypr8lpnl9t5qdekfp700x660qsgw284xvq4s09lqrqqk3m82
```
- **Directly tip the developer working on the features you like.** Check the [active PRs](https://github.com/RoboSats/robosats/pulls) and show your support to the developers with via Lightning tips. Simply write a message, for example "@developer_name, I would like to fund your development of this feature with 6000 Sats". The developer should reply with a LN invoice with a long expiration time.
- **Directly tip the developer working on the features you like.** Check the [active PRs](https://github.com/RoboSats/robosats/pulls) and show your support to the developers with via Lightning tips. Simply write a message, for example "@developer_name, I would like to fund your development of this feature with 6000 Sats". The developer should reply with an LN invoice with a long expiration time.
- **Tip the RoboSats devfund via Paynym (BIP47): [{{site.robosats.paynym}}](https://paynym.is/{{site.robosats.paynym}})** paynym code: