share2fedi/CONTRIBUTING.md

<!--
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!