toot-script-condivisione-su.../CONTRIBUTING.md

119 lines
4.3 KiB
Markdown
Raw Normal View History

2023-09-02 21:44:38 +02:00
<!--
This file is part of Share₂Fedi
https://github.com/kytta/share2fedi
SPDX-FileCopyrightText: © 2023 Nikita Karamov <me@kytta.dev>
SPDX-License-Identifier: CC0-1.0
-->
# Contributing guide
First off, thank you for considering contributing to Share₂Fedi! There are many
ways you can improve on the project:
- [write new and improve on the old code](#improving-code)
- [write documentation](#writing-documentation)
- [translate UI strings](#translating)
- [report bugs](#reporting-bugs)
Please, follow this guide if you want to contribute. We promise, it's not too
many rules! Following this helps us merge changes quicker!
Unsure where to begin contributing? You can start by looking through
[the help-wanted issues](https://github.com/kytta/share2fedi/labels/help%20wanted)!
## Improving code
Before you start, make sure you've got a fresh Node.js version (v18 should work)
installed. You'll also need to [install pnpm](https://pnpm.io/installation), as
this is our package manager of choice.
1. Fork the repository and clone it
2. Install dependencies:
```sh
pnpm install
```
3. To start a dev server, run:
```sh
pnpm dev
```
This server will auto-update on changes to the file
4. After implementing a feature, create a new Git branch and commit your changes
on it
5. Push the branch and open a PR.
### Adding support for other Fediverse projects
In order for a Fediverse project to be supported, it has to have a "Share" page
located at a fixed address. That means, that the address is the same for all
users and all frontends. For example, Mastodon's "Share" page is always at
`/share`. The share page should also accept the text of the post via URL
parameters. For example, Mastodon allows pre-filling the text of a post using
`?text=`. Lastly, it should be listed on
[fediverse.observer](https://fediverse.observer/).
If the Fediverse project satisfies these requirements, you can add it to
Share2Fedi. For this:
1. Add an entry to `supportedProjects` inside `src/lib/project.ts`.
- keep the list in alphabetical order
- the key should match the software name from NodeInfo/fediverse.observer
- the value should be an object of type `ProjectPublishConfig`. The endpoint
is the path to the "Share" page (leading slash optional).
- if the service you're adding is a flavour of an already supported service,
use the variable to reduce code duplication. See `mastodonConfig` for an
example
2. Pick an instance of the project you've added and visit
`/api/detect/<INSTANCE-DOMAIN>`. Make sure the detection is correct
3. Go to the `/` and try to share something to the instance. Make sure the
"Share" page opens with correct parameters.
## Writing documentation
Share₂Fedi's documentation is pretty complete at the moment, but you are free to
fix errors and to add clarifications. The only documentation we have is the
`README.md` and `CONTRIBUTING.md` that you're reading right now.
## Translating
Starting with v3, Share₂Fedi has a very primitive translation framework built
in. Despite it being simple, you can edit translations and add new languages in
form of JSON-based dictionaries.
There are two ways you can add/edit translations:
1. The JSON files under `src/i18n/translations` represent dictionaried for
different languages. The two-letter codes correspond to the ISO 639-1
language codes.
- to edit translations, just edit the files. Refer to
[the coding guide](#improving-code) for more information on how to do this.
2. [Weblate](https://translate.codeberg.org/engage/share2fedi/), a web-based
tool that simplifies this process.
- we use Codeberg's Weblate instance, which requires a Codeberg account. If
you have one, this is the easiest way to edit translations.
## Reporting bugs
> [!IMPORTANT]
> If you find a security vulnerability, do NOT open an issue. Email
> [Nikita Karamov](mailto:me@kytta.dev) instead.
If you find a bug you can't (or don't want to) fix yourself, don't hesitate
filing an issue. We do not have a preset issue template, but try to answer these
questions in the issue body:
1. What version of Share₂Fedi are you using?
2. How do you deploy it (Node/Vercel/Netlify/Cloudflare/Deno)?
3. What did you do?
4. What did you expect to see?
5. What did you see instead?
---
We are looking forward to your contributions!