139 lines
5.3 KiB
Markdown
139 lines
5.3 KiB
Markdown
<!--
|
|
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. [Weblate](https://hosted.weblate.org/engage/share2fedi/), a web-based tool
|
|
that simplifies this process.
|
|
- we use Hosted Weblate. You can login using any account. Make sure to set
|
|
the correct email so that the changes can be attributed to you!
|
|
- Weblate handles PRs automatically. You do not need to do anything other
|
|
than use it to edit translations
|
|
2. 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.
|
|
|
|
### Adding new languages
|
|
|
|
You may notice that adding a new language in Weblate or in the code does not add
|
|
it to the language dropdown. This is due to the i18n needing to define the
|
|
languages for the dropdown.
|
|
|
|
To add a new language, edit the `src/i18n/translations.ts` file. Import the JSON
|
|
file with the translations and add a new entry to the `languages` mapping.
|
|
|
|
> [!IMPORTANT]
|
|
> For the language name, use a **capitalized autonym**. An autonym
|
|
> is the name of the language in the language itself. You can consult CLDR or
|
|
> Wikipedia for this. It should be capitalized, if it makes sense in the
|
|
> language. It should NOT include the word "language" unless it's common to use
|
|
> it ("Bahasa Indonesia", but "Русский", not "русский язык")
|
|
>
|
|
> A good rule of thumb is to take the value that Wikipedia uses in their
|
|
> [language list](https://www.wikipedia.org/#js-lang-lists).
|
|
|
|
## 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!
|