forked from mastodon/mastodon
-
Notifications
You must be signed in to change notification settings - Fork 3
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Moving docs to tootsuite/documentation (mastodon#1550)
- Loading branch information
Showing
42 changed files
with
31 additions
and
1,845 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,46 +1 @@ | ||
| Sponsors | ||
| ======== | ||
|
|
||
| These people make the development of Mastodon possible through [Patreon](https://www.patreon.com/user?u=619786): | ||
|
|
||
| **Extra special Patrons** | ||
|
|
||
| - [World'sTallestLadder](https://mastodon.social/users/carcinoGeneticist) | ||
| - [Jimmy Tidey](https://mastodon.social/users/jimmytidey) | ||
| - [Kurtis Rainbolt-Greene](https://mastodon.social/users/krainboltgreene) | ||
| - [Kit Redgrave](https://socially.constructed.space/users/KitRedgrave) | ||
| - [Zeipher](https://mastodon.social/users/Zeipher) | ||
| - [Effy Elden](https://mastodon.social/users/effy) | ||
| - [Zoë Quinn](https://mastodon.social/users/zoequinn) | ||
|
|
||
| **Thank you to the following people** | ||
|
|
||
| - [Harris Bomberguy](https://mastodon.social/users/Hbomberguy) | ||
| - [Edward Saperia](https://nwspk.com) | ||
| - [Yoz Grahame](http://yoz.com/) | ||
| - [Jenn Kaplan](https://gay.crime.team/users/jkap) | ||
| - [Natalie Weizenbaum](https://mastodon.social/users/nex3) | ||
| - [Matteo De Micheli](http://matteodem.ch/) | ||
| - [BirdMachine](https://mastodon.social/users/BirdMachine) | ||
| - [Jessica Hayley](https://mastodon.social/users/jayhay) | ||
| - [Niels Roesen Abildgaard](http://hypesystem.dk/) | ||
| - [Zatnosk](https://github.com/Zatnosk) | ||
| - [Spex Bluefox](https://mastodon.social/users/Spex) | ||
| - [J. C. Holder](http://jcholder.com/) | ||
| - [glocal](https://mastodon.social/users/glocal) | ||
| - [jk](https://mastodon.social/users/jk) | ||
| - [C418](https://mastodon.social/users/C418) | ||
| - [halcy](https://icosahedron.website/users/halcy) | ||
| - [Extropic](https://gnusocial.no/extropic) | ||
| - [Pat Monaghan](http://iwrite.software/) | ||
| - TBD | ||
| - TBD | ||
| - TBD | ||
| - TBD | ||
| - TBD | ||
| - TBD | ||
| - TBD | ||
| - TBD | ||
| - TBD | ||
| - TBD | ||
| - TBD | ||
| [The documentation has moved to its own repository](https://github.com/tootsuite/documentation/blob/master/Contributing-to-Mastodon/Sponsors.md) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,48 +1 @@ | ||
| Translating | ||
| =========== | ||
|
|
||
| If you want to localise Mastodon into your language, here is how. | ||
|
|
||
| There are two parts to Mastodon, the server and the web client. The translations for the web client are in `app/assets/javascripts/components/locales`. For the server-side, the translations live in `config/locales` and are divided into different files. Here are all the files you’ll need to translate: | ||
|
|
||
| | Original file (English) | Location | Description | | ||
| |---|---|---| | ||
| | [`en.jsx`](/app/assets/javascripts/components/locales/en.jsx) | `app/assets/javascripts/components/locales/en.jsx` | Strings for the web client | | ||
| | [`en.yml`](/config/locales/en.yml) | `config/locales/en.yml` | Strings for general use | | ||
| | [`simple_form.en.yml`](/config/locales/simple_form.en.yml) | `config/locales/simple_form.en.yml` | Strings for the settings area | | ||
| | [`devise.en.yml`](/config/locales/devise.en.yml) | `config/locales/devise.en.yml` | Generic strings for Devise | | ||
| | [`doorkeeper.en.yml`](/config/locales/doorkeeper.en.yml) | `config/locales/doorkeeper.en.yml` | Generic strings for Doorkeeper | | ||
|
|
||
| ## Translating | ||
|
|
||
| If you use Github, first clone the Mastodon repository to your account. | ||
|
|
||
| 1. Duplicate the files in their folder and replace `en` in the filenames by your language’s standard two-letters code ([ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes)). | ||
| For instance `simple_form.en.yml` becomes `simple_form.es.yml` in the Spanish translation. | ||
| 2. Also replace the language code in the first lines of all the files, and the last line of the `.jsx` file. | ||
| 3. Translate the right-side values from English to your language. Keep the indentation and punctuation. | ||
|
|
||
| Since Devise and Doorkeeper are popular libraries, there may already be translation files for your language available on the Internet. | ||
|
|
||
| ## Declaring the language | ||
|
|
||
| The locales are mentioned in several other files. To activate your translation, add your language code to the different lists present in these files: | ||
|
|
||
| | File | Location | Comment | | ||
| |---|---|---| | ||
| | [`index.jsx`](/app/assets/javascripts/components/locales/index.jsx) | `app/assets/javascripts/components/locales/index.jsx` | 2 lines to add | | ||
| |[`mastodon.jsx`](/app/assets/javascripts/components/containers/mastodon.jsx) | `app/assets/javascripts/components/containers/mastodon.jsx` | 1 line to add + 1 list to complete | | ||
| | [`settings_helper.rb`](/app/helpers/settings_helper.rb) | `app/helpers/settings_helper.rb` | 1 line to add + your language’s name | | ||
| | [`application.rb`](/config/application.rb) | `config/application.rb` | 1 list to complete | | ||
|
|
||
| ## Sending the translation | ||
|
|
||
| You can then push the files to git and submit a pull request. | ||
|
|
||
| ## Testing the translation | ||
|
|
||
| Once the pull request is accepted, wait for the code to be deployed on a Mastodon instance. Log-in with your account there, and change the locale in the settings. Browse and use the website. See if everything makes sense in context and if anything seems out of place or breaks the layout. Invite other Mastodon users speaking your language to try it and give feedback. Make changes accordingly and update the translation. | ||
|
|
||
| ## Updating the translation | ||
|
|
||
| Keep an eye on the original English files in `app/assets/javascripts/components/locales` and `config/locales`. When they are updated, pass on the changes to your language files. For new strings, add the new lines to the same position and translate them. Once you’re finished with the updates, you can submit a new pull request. | ||
| [The documentation has moved to its own repository](https://github.com/tootsuite/documentation/blob/master/Contributing-to-Mastodon/Translating.md) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,50 +1 @@ | ||
| Protocol extensions | ||
| =================== | ||
|
|
||
| Some functionality in Mastodon required some additions to the protocols to enable seamless federation of those features: | ||
|
|
||
| ### Federation of blocks/unblocks | ||
|
|
||
| ActivityStreams was lacking verbs for block/unblock. Mastodon creates Salmon slaps for block and unblock events, which are not part of a user's public feed, but are nevertheless delivered to the target user. The intent of these Salmon slaps is not to notify the target user, but to notify the target user's server, so that it can perform any number of UX-related tasks such as removing the target user as a follower of the blocker, and/or displaying a message to the target user such as "You can't follow this person because you've been blocked" | ||
|
|
||
| The Salmon slaps have the exact same structure as standard follow/unfollow slaps, the verbs are namespaced: | ||
|
|
||
| - `http://mastodon.social/schema/1.0/block` | ||
| - `http://mastodon.social/schema/1.0/unblock` | ||
|
|
||
| ### Federation of sensitive material | ||
|
|
||
| Statuses can be marked as containing sensitive (or not safe for work) media. This is symbolized by a `<category term="nsfw" />` on the Atom entry | ||
|
|
||
| ### Federation of privacy features | ||
| #### Locked accounts and status privacy levels | ||
|
|
||
| Accounts and statuses have an access "scope": | ||
|
|
||
| Accounts can be "private" or "public". The former requires a follow request to be approved before a follow relationship can be established, the latter can be followed directly. | ||
|
|
||
| Statuses can be "private", "unlisted" or "public". Private must only be shown to the followers of the account or people mentioned in the status; public can be displayed publicly. Unlisted statuses may be displayed publicly but preferably outside of any spotlights e.g. "whole known network" or "public" timelines. | ||
|
|
||
| Namespace of the scope element is `http://mastodon.social/schema/1.0`. Example: | ||
|
|
||
| ```xml | ||
| <entry> | ||
| <!-- ... --> | ||
| <author> | ||
| <!-- ... --> | ||
| <mastodon:scope>private</mastodon:scope> | ||
| </author> | ||
| <!-- ... --> | ||
| <mastodon:scope>private</mastodon:scope> | ||
| </entry> | ||
| ``` | ||
|
|
||
| #### Follow requests | ||
|
|
||
| Mastodon uses the following Salmon slaps to signal a follow request, a follow request authorization and a follow request rejection: | ||
|
|
||
| - `http://activitystrea.ms/schema/1.0/request-friend` | ||
| - `http://activitystrea.ms/schema/1.0/authorize` | ||
| - `http://activitystrea.ms/schema/1.0/reject` | ||
|
|
||
| The activity object of the request-friend slap is the account in question. The activity object of the authorize and reject slaps is the original request-friend activity. Request-friend slap is sent to the locked account, when the end-user of that account decides, the authorize/reject decision slap is sent back to the requester. | ||
| [The documentation has moved to its own repository](https://github.com/tootsuite/documentation/blob/master/Extensions.md) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,36 +1 @@ | ||
| Index | ||
| ===== | ||
|
|
||
| **Mastodon** is a free, open-source GNU social-compatible social network server. A decentralized alternative to commercial platforms, it avoids the risks of a single company monopolizing your communication. Anyone can run Mastodon and participate in the social network seamlessly. | ||
|
|
||
| ### Using Mastodon | ||
| - [Frequently Asked Questions](Using-Mastodon/FAQ.md) | ||
| - [List of Mastodon instances](Using-Mastodon/List-of-Mastodon-instances.md) | ||
| - [Apps](Using-Mastodon/Apps.md) | ||
| - [User Guide](Using-Mastodon/User-guide.md) | ||
|
|
||
| ### Using the API | ||
| - [API documentation](Using-the-API/API.md) | ||
| - [Streaming API documentation](Using-the-API/Streaming-API.md) | ||
| - [Testing the API with cURL](Using-the-API/Testing-with-cURL.md) | ||
| - [OAuth details](Using-the-API/OAuth-details.md) | ||
| - [Tips for app developers](Using-the-API/Tips-for-app-developers.md) | ||
| - [Push notifications](Using-the-API/Push-notifications.md) | ||
|
|
||
| ### Running Mastodon | ||
| - [Production guide](Running-Mastodon/Production-guide.md) | ||
| - [Alternative: Running on Heroku](Running-Mastodon/Heroku-guide.md) | ||
| - [Development guide](Running-Mastodon/Development-guide.md) | ||
| - [Alternative: Development with Vagrant](Running-Mastodon/Vagrant-guide.md) | ||
| - [Administration guide](Running-Mastodon/Administration-guide.md) | ||
| - [Tuning Mastodon](Running-Mastodon/Tuning.md) | ||
|
|
||
| ### Contributing to Mastodon | ||
| - [Sponsors](Contributing-to-Mastodon/Sponsors.md) | ||
| - [Translate Mastodon in your language](Contributing-to-Mastodon/Translating.md) | ||
| - [Report bugs and submit ideas](https://github.com/tootsuite/mastodon/issues) | ||
|
|
||
| ### Protocols | ||
|
|
||
| - [List of used specs and RFCs for the federation](Specs-and-RFCs-used.md) | ||
| - [Extensions of the above protocols](Extensions.md) | ||
| [The documentation has moved to its own repository](https://github.com/tootsuite/documentation/blob/master/README.md) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,45 +1 @@ | ||
| Administration guide | ||
| ==================== | ||
|
|
||
| So, you have a working Mastodon instance... now what? | ||
|
|
||
| ## Turning into an admin | ||
|
|
||
| The following rake task: | ||
|
|
||
| RAILS_ENV=production bundle exec rails mastodon:make_admin USERNAME=alice | ||
|
|
||
| Would turn the local user "alice" into an admin. | ||
|
|
||
| ## Administration web interface | ||
|
|
||
| A user that is designated as `admin = TRUE` in the database is able to access a suite of administration tools: | ||
|
|
||
| * View, edit, silence, or suspend users - https://yourmastodon.instance/admin/accounts | ||
| * View PubSubHubbub subscriptions - https://yourmastodon.instance/admin/pubsubhubbub | ||
| * View domain blocks - https://yourmastodon.instance/admin/domain_blocks | ||
| * Sidekiq dashboard - https://yourmastodon.instance/sidekiq | ||
| * PGHero dashboard for PostgreSQL - https://yourmastodon.instance/pghero | ||
| * Edit site settings - https://yourmastodon.instance/admin/settings | ||
|
|
||
| ## Site settings | ||
|
|
||
| Your site settings are stored in the `settings` database table, and editable through the admin interface at https://yourmastodon.instance/admin/settings. | ||
|
|
||
| You are able to set the following settings: | ||
|
|
||
| - Site title | ||
| - Contact username | ||
| - Contact email | ||
| - Site description | ||
| - Site extended description | ||
|
|
||
| You may wish to use the extended description (shown at https://yourmastodon.instance/about/more ) to display content guidelines or a user agreement (see https://mastodon.social/about/more for an example). | ||
|
|
||
| ## Confirming Users Manually | ||
|
|
||
| The following rake task: | ||
|
|
||
| RAILS_ENV=production bundle exec rails mastodon:confirm_email USER_EMAIL=alice@alice.com | ||
|
|
||
| Will confirm a user manually, in case they don't have access to their confirmation email for whatever reason. | ||
| [The documentation has moved to its own repository](https://github.com/tootsuite/documentation/blob/master/Running-Mastodon/Administration-guide.md) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,50 +1 @@ | ||
| Development guide | ||
| ================= | ||
|
|
||
| **Don't use Docker to do development**. It's a quick way to get Mastodon running in production, it's **really really inconvenient for development**. Normally in Rails development environment you get hot reloading of backend code and on-the-fly compilation of assets like JS and CSS, but you lose those benefits by compiling a Docker image. If you want to contribute to Mastodon, it is worth it to simply set up a proper development environment. | ||
|
|
||
| In fact, all you need is described in the [production guide](Production-guide.md), **with the following exceptions**. You **don't** need: | ||
|
|
||
| - Nginx | ||
| - SystemD | ||
| - An `.env.production` file. If you need to set any environment variables, you can use an `.env` file | ||
| - To prefix any commands with `RAILS_ENV=production` since the default environment is "development" anyway | ||
| - Any cronjobs | ||
|
|
||
| The command to install project dependencies does not require any flags, i.e. simply | ||
|
|
||
| bundle install | ||
|
|
||
| By default the development environment wants to connect to a `mastodon_development` database on localhost using your user/ident to login to Postgres (i.e. not a md5 password) | ||
|
|
||
| You can run Mastodon with: | ||
|
|
||
| rails s | ||
|
|
||
| And open `http://localhost:3000` in your browser. Background jobs run inline (aka synchronously) in the development environment, so you don't need to run a Sidekiq process. | ||
|
|
||
| By default, your development environment will have an admin account created for you to use - the email address will be `admin@YOURDOMAIN` (e.g. admin@localhost:3000) and the password will be `mastodonadmin`. | ||
|
|
||
| You can run tests with: | ||
|
|
||
| rspec | ||
|
|
||
| You can check localization status with: | ||
|
|
||
| i18n-tasks health | ||
|
|
||
| You can check code quality with: | ||
|
|
||
| rubocop | ||
|
|
||
| ## Development tips | ||
|
|
||
| You can use a localhost->world tunneling service like ngrok if you want to test federation, **however** that should not be your primary mode of operation. If you want to have a permanently federating server, set up a proper instance on a VPS with a domain name, and simply keep it up to date with your own fork of the project while doing development on localhost. | ||
|
|
||
| Ngrok and similar services give you a random domain on each start up. This is good enough to test how the code you're working on handles real-world situations. But as soon as your domain changes, for everybody else concerned you're a different instance than before. | ||
|
|
||
| Generally, federation bits are tricky to work on for exactly this reason - it's hard to test. And when you are testing with a disposable instance you are polluting the databases of the real servers you're testing against, usually not a big deal but can be annoying. The way I have handled this so far was thus: I have used ngrok for one session, and recorded the exchanges from its web interface to create fixtures and test suites. From then on I've been working with those rather than live servers. | ||
|
|
||
| I advise to study the existing code and the RFCs before trying to implement any federation-related changes. It's not *that* difficult, but I think "here be dragons" applies because it's easy to break. | ||
|
|
||
| If your development environment is running remotely (e.g. on a VPS or virtual machine), setting the `REMOTE_DEV` environment variable will swap your instance from using "letter opener" (which launches a local browser) to "letter opener web" (which collects emails and displays them at /letter_opener ). | ||
| [The documentation has moved to its own repository](https://github.com/tootsuite/documentation/blob/master/Running-Mastodon/Development-guide.md) |
Oops, something went wrong.