wholetrans/docs-mastodon
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Update content for 4.0 (part 1) (#991)

Browse source 
* add rules

* join date on profiles

* deprecate follow scope

* deprecate identity proofs

* familiar followers

* use definition lists instead of tables for defining activitypub properties

* reformat notifications page into markdown

* fix broken links to publicKey header

* Application website is now nullable

* update environment variables added and removed

* fix typo

* fix heading level

* min_id and max_id can be used at the same time (3.3)

* fix typo

* new tootctl options

* reformat tootctl page to use definition lists for params

* add rules and configuration to Instance

* fix typo

* refactor instance api page

* 3.3.0 duration on mutes

* 3.3.0 mute_expires_at

* improve section headings

* 3.4.0 resend email confirmation api

* 3.4.0 policy on push subscriptions

* 3.4.0 add details to account registration error

* refactor accounts api page and start adding relrefs to entity pages

* 3.4.0 accounts/lookup api

* add see also to accounts methods

* add more see-also links

* 3.5.0 appeal mod decisions

* 3.5.0 reformat reports and add category/rule_ids params

* document report entity and missing responses

* fix typos

* fix relrefs and url schema, add aliases to old urls

* add archetypes for new methods/entities

* update archetypes with see-also stubs

* clearer presentation of rate limits

* announcements api methods

* refactor apps methods

* refactor bookmarks methods + some anchors

* refactor conversations methods

* custom_emojis methods refactor

* anchors

* refactor directory methods

* refactor domain_blocks methods

* add see also to emails methods

* fix page relref shortcodes to specific methods + refactor endorsements methods

* min_id max_id

* refactor favourites methods

* refactor featured_tags methods

* refactor filters methods, make path params consistent, i18n required shortcode

* follow_requests methods

* lists methods

* markers methods

* forgot to add entity links

* media methods, also fix formatting of some json errors

* mutes methods, add more see-also links

* oembed methods

* preferences methods

* proofs methods

* push methods

* suggestions methods

* 3.5.0 add new trend types, fix formatting

* refactor streaming methods

* refactor oauth methods

* note that streaming api casts payload to string

* refactor search methods

* refactor polls methods

* remove unnecessary link

* reformat scheduled_statuses methods

* reformat timelines methods

* reformat statuses methods

* 3.5.0 editing statuses

* consistent use of array brackets in form data parameters

* update dev setup guide, add vagrant and clean up text

* add admin/accounts methods

* 3.6 role entity

* admin/accounts methods v2

* minor fix

* stub admin/reports methods

* document admin reports

* add 403 example to methods archetype

* cleanup entities for admin reports and add new attrs

* 3.6.0 domain allows methods + normalize admin entity namespace

* fix search-and-replace error

* add aliases for admin entities

* 3.6.0 canonical email blocks entity

* 3.5.0 admin/retention api

* 3.5.0 add admin::ip doc

* 3.5.0 admin/reports

* 3.6.0 admin/domain_allows

* 3.5.0 admin/dimensions

* 3.6.0 permissions and roles

* minor formatting fix

* add anchor link to headings

* checkpoint

* add update commands to dev env setup guide

* change mentions of v3.6 to v4.0

* tootctl now uses custom roles

* fix formatting

* v2 instance api

* update frontmatter, add better titles to pages

* minor wording change

* consistency

* add more aliases

* add placeholders and WIP notices

* explain link pagination and stub out todos

* switch baseURL to https

* 422 on reports with rules but category!=violation

* document bug fixes

* fix typo

* remove duplicate API method definition

* s/tootsuite/mastodon for github links

* remove unnecessary escaping

* s/tootsuite/mastodon in Entity archetype

* add missing nullable shortcode

* clarify oauth scope when requesting a user token

* api/v2/media now synchronous for images

* DISALLOW_UNAUTHENTICATED_API_ACCESS

* add undocumented env variables

* add instance domain blocks and extended description api

* add SMTP_ENABLE_STARTTLS

* add description to SMTP_ENABLE_STARTTLS

* take suggestions from open PRs

* normalize links and flavour language

* Fully document streaming API based on source code

* Add mention of MIME types

* bump to ruby 3.0.4

* clarify how to check on async media processing

* validation of replies_policy

* remove TODOs on admin account action

* EmailDomainBlocks

* IpBlocks

* Admin::DomainBlock

* remove TODOs

* following hashtags

* followed_tags

* remove reference to unused parameter

* add new oauth scopes for admin blocks and allows

* fix command signature for i18n-tasks normalize

* reformat code structure page

* document fixes for following tags (assume 4.0.3)

* Add warning about pre-4.0 hardcoded roles

* add note about case sensitivity

* remove use of 'simply' from docs

* remove reference to silencing

* add reference to IDN normalization for verified links

* add lang parameter
This commit is contained in:
trwnh 2022-11-20 00:34:38 -06:00 • committed by GitHub
parent 69e9017730
commit 3628b6d434
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
225 changed files with 22675 additions and 11631 deletions
Download patch file Download diff file Expand all files Collapse all files

73
content/en/dev/code.md
View file

@ -17,45 +17,62 @@ The following overview should not be seen as complete or authoritative, but as a
#### Ruby {#ruby}
| Path | Description |
| :--- | :--- |
| `app/controllers` | Code that binds business logic to templates |
| `app/helpers` | Code that can be used from views, i.e. common operations |
| `app/lib` | Code that doesn’t fit in the other categories |
| `app/models` | Code that represents data entities |
| `app/serializers` | Code that generates JSON from models |
| `app/services` | Complex logical operations involving multiple models |
| `app/views` | Templates for generating HTML or other output |
| `app/workers` | Code that executes outside the request-response cycle |
| `spec` | Automated test suite |
`app/controllers`
: Code that binds business logic to templates
`app/helpers`
: Code that can be used from views, i.e. common operations
`app/lib`
: Code that doesn’t fit in the other categories
`app/models`
: Representation of data entities and their associated methods
`app/policies`
: Permission checks and other validations, before calling related methods
`app/serializers`
: Code that generates JSON from models
`app/services`
: Complex logical operations involving multiple models
`app/views`
: Templates for generating HTML or other output
`app/workers`
: Code that executes outside the request-response cycle
`spec`
: Automated test suite
#### JavaScript {#javascript}
| Path | Description |
| :--- | :--- |
| `app/javascript/mastodon` | Code for the multi-column React.js application |
| `app/javascript/packs` | Code for non-React.js pages |
`app/javascript/mastodon`
: Code for the frontend React.js application
`app/javascript/packs`
: Code for non-React.js pages
#### CSS and other assets {#assets}
| Path | Description |
| :--- | :--- |
| `app/javascript/images` | Images |
| `app/javascript/styles` | Code that turns into CSS via Sass |
`app/javascript/images`
: Images
`app/javascript/styles`
: Code that turns into CSS via Sass
#### Localizations {#localizations}
| Path | Description |
| :--- | :--- |
| `config/locales` | Server-side localizations in the YML format |
| `app/javascript/mastodon/locales` | Client-side localizations in the JSON format |
`config/locales`
: Server-side localizations in the YML format
### Localization maintenance {#localization-maintenance}
`app/javascript/mastodon/locales`
: Client-side localizations in the JSON format
All locale files are normalized to ensure consistent formatting and key order, which minimizes changesets in version control.
| Command | Description |
| :--- | :--- |
| `i18n-tasks normalize` | Normalize server-side translations |
| `yarn run manage:translations` | Normalize client-side translations |
- Run `bundle exec i18n-tasks normalize` to normalize server-side translations
- Run `yarn run manage:translations` to normalize client-side translations

190
content/en/dev/routes.md
View file

@ -7,7 +7,7 @@ menu:
parent: dev
---
{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/config/routes.rb" caption="config/routes.rb" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/config/routes.rb" caption="config/routes.rb" >}}
## Explanation of routes {#routes}
@ -67,7 +67,7 @@ Maps to HTTP DELETE. Handled by the \#destroy action in a controller.
### /.well-known/host-meta {#host-meta}
Extensible Resource Descriptor \(XRD\). Advertises existence of Webfinger.
Extensible Resource Descriptor (XRD). Advertises existence of Webfinger.
### /.well-known/nodeinfo {#nodeinfo}
@ -75,7 +75,7 @@ Maps to NodeInfo 2.0 endpoint at `/nodeinfo/2.0`, used for advertising software
### /.well-know/webfinger {#webfinger}
Used for discovering ActivityPub actor id. See [Spec compliance &gt; WebFinger]({{< relref "../spec/webfinger.md" >}}) for more information.
Used for discovering ActivityPub actor id. See [Spec compliance &gt; WebFinger]({{< relref "spec/webfinger" >}}) for more information.
### /.well-known/change-password {#change-password}
@ -94,8 +94,8 @@ The sections below this point are under construction.
* `/users/username` = user URI
* `/users/username/remote_follow` = remote follow dialog
* `/users/username/statuses/id` = status URI
* `/@username` = "toots" tab
* `/@username/with_replies` = "toots and replies" tab
* `/@username` = "posts" tab
* `/@username/with_replies` = "posts and replies" tab
* `/@username/media` = "media" tab
* `/@username/tagged/:hashtag` = tagged statuses by user
* `/@username/:status_id` = status permalink
@ -113,95 +113,95 @@ The sections below this point are under construction.
* /api/oembed
* /api/proofs
* /api/v1
* [statuses]({{< relref "../methods/statuses/" >}}) \[create, show, destroy\]
* reblogged\_by \[index\]
* favourited\_by \[index\]
* reblog \[create\]
* unreblog \[POST reblog\#destroy\]
* favourite \[create\]
* unfavourite \[POST favourites\#destroy\]
* bookmark \[create\]
* unbookmark \[POST bookmarks\#destroy\]
* mute \[create\]
* unmute \[POST mutes\#destroy\]
* pin \[create\]
* unpin \[POST pins\#destroy\]
* context \[GET\]
* [timelines]({{< relref "../methods/timelines/" >}})
* home \[show\]
* public \[show\]
* tag \[show\]
* list \[show\]
* [streaming]({{< relref "../methods/timelines/streaming.md" >}}) \[index\]
* [custom\_emojis]({{< relref "../methods/instance/custom_emojis.md" >}}) \[index\]
* [suggestions]({{< relref "../methods/accounts/suggestions.md" >}}) \[index, destroy\]
* [scheduled\_statuses]({{< relref "../methods/statuses/scheduled_statuses.md" >}}) \[index, show, update, destroy\]
* [preferences]({{< relref "../methods/accounts/preferences.md" >}}) \[index\]
* [conversations]({{< relref "../methods/timelines/conversations.md" >}}) \[index, destroy\]
* read \[POST\]
* [media]({{< relref "../methods/statuses/media.md" >}}) \[create, update\]
* [blocks]({{< relref "../methods/accounts/blocks.md" >}}) \[index\]
* [mutes]({{< relref "../methods/accounts/mutes.md" >}}) \[index\]
* [favourites]({{< relref "../methods/accounts/favourites.md" >}}) \[index\]
* [bookmarks]({{< relref "../methods/accounts/bookmarks.md" >}}) \[index\]
* [reports]({{< relref "../methods/accounts/reports.md" >}}) \[create\]
* [trends]({{< relref "../methods/instance/trends.md" >}}) \[index\]
* [filters]({{< relref "../methods/accounts/filters.md" >}}) \[index, create, show, update, destroy\]
* [endorsements]({{< relref "../methods/accounts/endorsements.md" >}}) \[index\]
* [markers]({{< relref "../methods/timelines/markers.md" >}}) \[index, create\]
* [apps]({{< relref "../methods/apps/" >}}) \[create\]
* verify\_credentials \[credentials\#show\]
* [instance]({{< relref "../methods/instance/" >}}) \[show\]
* peers \[index\]
* activity \[show\]
* [domain\_blocks]({{< relref "../methods/accounts/domain_blocks.md" >}}) \[show, create, destroy\]
* [directory]({{< relref "../methods/instance/directory.md" >}}) \[show\]
* [follow\_requests]({{< relref "../methods/accounts/follow_requests.md" >}}) \[index\]
* authorize \[POST\]
* reject \[POST\]
* [notifications]({{< relref "../methods/notifications/" >}}) \[index, show\]
* clear \[POST\]
* dismiss \[POST\]
* [accounts]({{< relref "../methods/accounts/" >}})
* verify\_credentials \[GET credentials\#show\]
* update\_credentials \[PATCH credentials\#update\]
* search \[show \(search\#index\)\]
* relationships \[index\]
* [accounts]({{< relref "../methods/accounts/" >}}) \[create, show\]
* statuses \[index accounts/statuses\]
* followers \[index accounts/follower\_accounts\]
* following \[index accounts/following\_accounts\]
* lists \[index accounts/lists\]
* identity\_proofs \[index accounts/identity\_proofs\]
* follow \[POST\]
* unfollow \[POST\]
* block \[POST\]
* unblock \[POST\]
* mute \[POST\]
* unmute \[POST\]
* pin \[POST\]
* unpin \[POST\]
* [lists]({{< relref "../methods/timelines/lists.md" >}}) \[index, create, show, update, destroy\]
* accounts \[POST accounts/pins\#destroy\]
* [featured\_tags]({{< relref "../methods/accounts/featured_tags.md" >}}) \[index, create, destroy\]
* suggestions \[GET suggestions\#index\]
* [polls]({{< relref "../methods/statuses/polls.md" >}}) \[create, show\]
* votes \[create polls/votes\]
* [push]({{< relref "../methods/notifications/push.md" >}})
* subscription \[create, show, update, destroy\]
* [admin]({{< relref "../methods/admin.md" >}})
* accounts \[index, show\]
* enable \[POST\]
* unsilence \[POST\]
* unsuspend \[POST\]
* approve \[POST\]
* reject \[POST\]
* action \[create account\_actions\]
* reports \[index, show\]
* assign\_to\_self \[POST\]
* unassign \[POST\]
* reopen \[POST\]
* resolve \[POST\]
* [statuses]({{< relref "methods/statuses" >}}) [create, show, destroy]
* reblogged\_by [index]
* favourited\_by [index]
* reblog [create]
* unreblog [POST reblog\#destroy]
* favourite [create]
* unfavourite [POST favourites\#destroy]
* bookmark [create]
* unbookmark [POST bookmarks\#destroy]
* mute [create]
* unmute [POST mutes\#destroy]
* pin [create]
* unpin [POST pins\#destroy]
* context [GET]
* [timelines]({{< relref "methods/timelines" >}})
* home [show]
* public [show]
* tag [show]
* list [show]
* [streaming]({{< relref "methods/streaming" >}}) [index]
* [custom\_emojis]({{< relref "methods/custom_emojis" >}}) [index]
* [suggestions]({{< relref "methods/suggestions" >}}) [index, destroy]
* [scheduled\_statuses]({{< relref "methods/scheduled_statuses" >}}) [index, show, update, destroy]
* [preferences]({{< relref "methods/preferences" >}}) [index]
* [conversations]({{< relref "methods/conversations" >}}) [index, destroy]
* read [POST]
* [media]({{< relref "methods/media" >}}) [create, update]
* [blocks]({{< relref "methods/blocks" >}}) [index]
* [mutes]({{< relref "methods/mutes" >}}) [index]
* [favourites]({{< relref "methods/favourites" >}}) [index]
* [bookmarks]({{< relref "methods/bookmarks" >}}) [index]
* [reports]({{< relref "methods/reports" >}}) [create]
* [trends]({{< relref "methods/trends" >}}) [index]
* [filters]({{< relref "methods/filters" >}}) [index, create, show, update, destroy]
* [endorsements]({{< relref "methods/endorsements" >}}) [index]
* [markers]({{< relref "methods/markers" >}}) [index, create]
* [apps]({{< relref "methods/apps" >}}) [create]
* verify\_credentials [credentials\#show]
* [instance]({{< relref "methods/instance" >}}) [show]
* peers [index]
* activity [show]
* [domain\_blocks]({{< relref "methods/domain_blocks" >}}) [show, create, destroy]
* [directory]({{< relref "methods/directory" >}}) [show]
* [follow\_requests]({{< relref "methods/follow_requests" >}}) [index]
* authorize [POST]
* reject [POST]
* [notifications]({{< relref "methods/notifications" >}}) [index, show]
* clear [POST]
* dismiss [POST]
* [accounts]({{< relref "methods/accounts" >}})
* verify\_credentials [GET credentials\#show]
* update\_credentials [PATCH credentials\#update]
* search [show (search\#index)]
* relationships [index]
* [accounts]({{< relref "methods/accounts" >}}) [create, show]
* statuses [index accounts/statuses]
* followers [index accounts/follower\_accounts]
* following [index accounts/following\_accounts]
* lists [index accounts/lists]
* identity\_proofs [index accounts/identity\_proofs]
* follow [POST]
* unfollow [POST]
* block [POST]
* unblock [POST]
* mute [POST]
* unmute [POST]
* pin [POST]
* unpin [POST]
* [lists]({{< relref "methods/lists" >}}) [index, create, show, update, destroy]
* accounts [POST accounts/pins\#destroy]
* [featured\_tags]({{< relref "methods/featured_tags" >}}) [index, create, destroy]
* suggestions [GET suggestions\#index]
* [polls]({{< relref "methods/polls" >}}) [create, show]
* votes [create polls/votes]
* [push]({{< relref "methods/push" >}})
* subscription [create, show, update, destroy]
* [admin]({{< relref "methods/admin" >}})
* accounts [index, show]
* enable [POST]
* unsilence [POST]
* unsuspend [POST]
* approve [POST]
* reject [POST]
* action [create account\_actions]
* reports [index, show]
* assign\_to\_self [POST]
* unassign [POST]
* reopen [POST]
* resolve [POST]
* /api/v2
* [search]({{< relref "../methods/search.md" >}}) \[GET search\#index\]
* [search]({{< relref "methods/search" >}}) [GET search\#index]

96
content/en/dev/setup.md
View file

@ -7,47 +7,99 @@ menu:
parent: dev
---
{{< hint style="danger" >}}
This page is under construction.
{{< /hint >}}
## Quick start with Vagrant {#vagrant}
### Pre-requisites {#prerequisites}
For convenience, the Mastodon repository includes a Vagrantfile for quickly setting up a development environment without manual configuration. To use this development environment, install [Vagrant](https://vagrantup.com) using a binary executable or through your package manager.
You can follow the [pre-requisites instructions from the production guide](https://docs.joinmastodon.org/admin/install/), but do not create a `mastodon` user. You also don't have to install `nginx`, `certbot` and `python-certbot-nginx` as the development environment brings its own webserver. Setting up and running a development environment has been proven successful over WSL2 as well if you are on Windows.
Once you have Vagrant installed, for convenience, it is recommended to install a plugin to automatically update your machine's hosts file. This will allow you to access the dev environment at `http://mastodon.local` without manually editing the hosts file yourself. To do so:
```sh
vagrant plugin install vagrant-hostsupdater
```
The virtual machine can then be started:
```sh
vagrant up
```
Once the virtual machine has been started, you may launch the Foreman task executor to launch the various Mastodon processes:
```sh
vagrant ssh -c "cd /vagrant && foreman start"
```
Once the Mastodon processes have fully started up, you can load `http://mastodon.local` in your browser to access the Mastodon instance within the VM. You can log in as the default admin user with the username `admin@mastodon.local` and the password `mastodonadmin`.
Any changes to the source code will be reflected after saving your files.
To reset the VM to a fresh state, you can destroy it and bring it up again:
```sh
vagrant destroy
vagrant up
```
## Manual install from source {#manual}
You can follow the [pre-requisites instructions from the production guide]({{<relref "admin/install">}}), but do not create a `mastodon` user. You also don't have to install `nginx`, `certbot` and `python-certbot-nginx` as the development environment brings its own webserver. Setting up and running a development environment has been proven successful over WSL2 as well if you are on Windows.
### Setup {#setup}
Run following commands in the project directory `bundle install`, `yarn install`.
Run the following commands in the project directory:
In the development environment, Mastodon will use PostgreSQL as the currently signed-in Linux user using the `ident` method, which usually works out of the box. The one command you need to run is `rails db:setup` which will create the databases `mastodon_development` and `mastodon_test`, load the schema into them, and then create seed data defined in `db/seed.rb` in `mastodon_development`. The only seed data is an admin account with the credentials `admin@localhost:3000` / `mastodonadmin`.
```sh
bundle install
yarn install
```
> Please keep in mind, by default Mastodon will run on port 3000. If you configure a different port for it, the generated admin account will use that number.
In the development environment, Mastodon will use PostgreSQL as the currently signed-in Linux user using the `ident` method. Ensure that you have created a Postgres user and database for your current signed-in user:
If `rails db:setup` gives you the Postgres error:
```sh
sudo -u postgres createuser $YOUR_USERNAME_HERE --createdb
```
ActiveRecord::NoDatabaseError: FATAL: role "your_user_name" does not exist
You can now create the databases `mastodon_development` and `mastodon_test`, load the schema into them, and create seed data defined in `db/seeds/` into `mastodon_development`.
(where `your_user_name` is your username), then run:
```sh
rails db:setup
```
sudo -u postgres createuser your_user_name --createdb
You can now launch `http://localhost:3000` in your browser and log in with the default admin user (`admin@localhost:3000` / `mastodonadmin`).
This will create the necessary Postgres user with the permission to create a database.
{{<hint style="warning">}}
By default, Mastodon will run on port 3000. If you configure a different port for it, the generated admin account will use that number as well.
{{</hint>}}
### Running {#running}
There are multiple processes that need to be run for the full set of Mastodon’s functionality, although they can be selectively omitted. To run all of them with just one command, you can install Foreman with `gem install foreman --no-document` and then use:
There are multiple processes that need to be run for the full set of Mastodon’s functionality, although they can be selectively omitted. To run all of them with just one command, you can install and use Foreman:
```text
```sh
gem install foreman --no-document
foreman start
```
In the Mastodon directory. This will start processes defined in `Procfile.dev`, which will give you: A Rails server, a Webpack server, a streaming API server, and Sidekiq. Of course, you can run any of those things stand-alone depending on your needs.
This will start processes defined in `Procfile.dev`, which will give you: A Rails server, a Webpack server, a streaming API server, and Sidekiq. Of course, you can run any of those things stand-alone depending on your needs.
### Testing {#testing}
## Useful commands for testing {#testing}
| Command | Description |
| :--- | :--- |
| `rspec` | Run the Ruby test suite |
| `yarn run test` | Run the JavaScript test suite |
| `rubocop` | Check the Ruby code for conformance with our code style |
`rspec`
: Run the Ruby test suite
`yarn run test`
: Run the JavaScript test suite
`rubocop`
: Check the Ruby code for conformance with our code style
## Updating your development instance {#update}
`bundle install`
: Update Ruby gems and install any new dependencies
`yarn install`
: Update Javascript packages and install any new dependencies
`RAILS_ENV=development rails db:migrate`
: Run new database migrations for your development instance's database