Thank you very much for your interest in improving Linkbox.
In this guide, you will learn how the project is structured and how you can get involved.
Linkbox is a hybrid application for the Android operating system. We use TypeScript, React, Ionic, Capacitor, Redux and i18next. We adhere to Conventional Commits, Semantic Versioning, Keep A Changelog, Conventional Comments, GitHub Flow. We use Prettier to format our code. For translations, we use the hosted Weblate service.
- Ionic Framework provides the UI components to get the native look and feel. It also comes with a handy CLI tool to automate many tasks
- Capacitor is used to bridge our web application with the operating system. It provides plug-ins to talk to native APIs (such as storage, file system etc.). Capacitor also takes care of "converting" our web application into a native one by creating the necessary native project files to build the final application package
- React is the view library used to build and structure our user interface as reactive components
- TypeScript is the programming language that we use in the project and is a superset of JavaScript
- Redux is the state management library for our user interface. We use Redux in combination with React in order to centralize our application's state
- i18next provides the internationalization (i18n) infrastructure for our application. We use it to translate our application to different languages
- Semantic Versioning defines how we version our application
- Conventional Commits is the ruleset to define our commit messages
- Keep A Changelog is the guideline used to define the structure of our changelog file
- Conventional Comments facilitates communication by standardizing comments in our project
- GitHub Flow defines our source code contribution workflow
- Prettier is used to format our code
android
contains native files for our project and can be opened in Android Studio to create the application package. We usually don't have to touch this folder manually since Capacitor handles itpublic
contains static assets like images and also the main HTML file for our applicationmetadata
contains Fastlane meta data about this application and is used to submit details to F-Droid and Play Storesrc
contains the source code of our application and is the place where you will most likely workcomponents
contains our UI componentsdata
contains every related with (persisted) data. If you are using the same value (which is not state) more than once across several components, you may want to declare it as a constant. Here we also find the storage adapter, which is responsible for interacting with the operating system's storage and file systemhooks
contains all the custom created hooks for our UI components. If you are using the same logic across the several components, you should outsource it to a custom hooklocales
contains the translations as JSON filesstore
contains all modules related to state management
src
index.tsx
is the application's main entrypoint of the application andApplication.tsx
is the root UI component which binds the centralized state onto our applicationMainPage.tsx
is the main view and includes all the sub-componentsstore.ts
represents the application's statei18n.ts
provides the internationalization infrastructure of our application
If you don't have a GitHub account, you can also submit your contributions by email to the following address: [email protected]
- When filing an issue, use the issue templates
- When submitting changes, attach a
.patch
file
- Open a new issue
- Describe the problem using the rules of Conventional Comments and our issue template for bug reports
- If not already existing, create a new issue describing the problem and follow the rules of Conventional Comments
- Create a fork of this project
- Clone that forked repository to your local machine
- Create a new branch respecting GitHub Flow rules (e.g. use
increase-rate-limit
as branch name) - Run
npm install
to install the project's dependencies - Run
npm run develop
to start the development server - Optionally run
npm develop:android
for a live preview on your Android device - Do your changes
- Make sure that the linter in the terminal does not display any errors
- Run
npm run format
to format your code using Prettier - Run
npm run sync
to synchronize the application's native project files with the your changes in the web application - Run
npm run open
to open Android Studio where you can build the native package and run it on a physical or emulated device - Test your changes and make sure nothing is broken
- Commit your changes with a message formatted according to Conventional Commits (e.g.
fix: increase rate limit
) - Push the changes
- Open a pull request on this original repository and name it using the Conventional Commits convention (e.g.
fix: increase rate limit
...fixes #12345
) and link it to the respective issue
You can either contribute translations using the Weblate web interface (preferred) or by creating and modifying the JSON file of the specific language.
- Use the workflow for doing changes (see above Doing Changes)
- Create or modify the language file in
src/locales
using the BCP 47 format (e.g.de.json
orfr-CA.json
) - Make the translations
- When adding translations: Open the i18n file
src/i18n.ts
and add your newly created JSON file to the import statements (e.g.import canadianFrench from "./locales/fr-CA"
) and add the imported value to theusedLanguages
array (e.g.[foo, bar,
canadianFrench]
)
Follow the instructions on the Weblate page.