From 13a1d2bc555a1866494b423dde2ef5a8589a893f Mon Sep 17 00:00:00 2001 From: Nikita Karamov Date: Sat, 2 Sep 2023 21:44:38 +0200 Subject: [PATCH] Add contributing guide --- CONTRIBUTING.md | 118 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 118 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..ad2470c --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,118 @@ + + +# 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/`. 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!