share2fedi/CONTRIBUTING.md

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
• write documentation
• translate UI strings
• report 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!

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, as this is our package manager of choice.

1. Fork the repository and clone it

2. Install dependencies:

   pnpm install
   

3. To start a dev server, run:

   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.

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, 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 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.

Reporting bugs

Important

If you find a security vulnerability, do NOT open an issue. Email Nikita Karamov 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!