From a235e5480ea150e29e6f8bd18581609494a154bc Mon Sep 17 00:00:00 2001 From: mariachrisochoou <115141097+mariachrisochoou@users.noreply.github.com> Date: Mon, 29 Apr 2024 19:18:45 +0300 Subject: [PATCH] added installing guide & fixed the format (#349) This is a documentation fixed. I fixed the format, added a table of contents and two new sections for installing the application as a first-time contributor and for the application architecture. I think these things are helpful for a newcomer to understand the way the project works and we can enrich it with all the different components of the app. --------- Co-authored-by: TrianguloY --- docs/CONTRIBUTING.md | 57 +++++++++++++++++++++++++++++++++++--------- 1 file changed, 46 insertions(+), 11 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 1f146705..d25e006c 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -1,4 +1,29 @@ -### For coder/developer: +# Contribution Documentation + +### Table of Contents + +- [For translator](#for-translator) +- [For coder/developer](#for-coderdeveloper) +- [Installing UrlChecker in Android Studio](#installing-urlchecker-in-android-studio) +- [App Architecture](#app-architecture) + +## For translator: + +You are free to propose one or more translations, or to update any existing one. Be sure of your work before providing it to the developers, who cannot verify it. You can translate it using [Weblate](https://hosted.weblate.org/engage/urlcheck/), as a [pull request](https://github.com/TrianguloY/UrlChecker/pulls)/[issue](https://github.com/TrianguloY/UrlChecker/issues/new) titled `{locale} Translation proposal` or by sending the files by email to [TrianguloY](https://github.com/TrianguloY). + +For manual translation, there are two independent things to translate: + +- **App strings**: the [`strings.xml`](../app/src/main/res/values/strings.xml) file + - Translate all texts between the `` and `` tags. + - Remember to insert a backslash `\` before any apostrophe `'`, or enclose all text in quotes `"` + - Place the translated file in the corresponding `./app/src/main/res/values-{locale}/` folder + +- **Store strings**: the [`title.txt`](../app/src/main/play/listings/en-US/title.txt) [`short-description.txt`](../app/src/main/play/listings/en-US/short-description.txt) and/or [`full-description.txt`](../app/src/main/play/listings/en-US/full-description.txt) files + - Place the translated files in the corresponding `./app/src/main/play/listings/{locale}/` folder + +Note: if you are unsure the locale prefix of a specific language you can find it [here](https://countrycode.org/). + +## For coder/developer: We don't have a coding style, but try to keep it similar to existing code, with just a couple notes: @@ -8,18 +33,28 @@ We don't have a coding style, but try to keep it similar to existing code, with You can check existing code to see examples, but be aware that some are not perfect. In doubt, just ask. -### For translator: +## Installing UrlChecker in Android Studio -You are free to propose one or more translations, or to update any existing one. Be sure of your work before providing it to the developers, who cannot verify it. You can translate it using [Weblate](https://hosted.weblate.org/engage/urlcheck/), as a [pull request](https://github.com/TrianguloY/UrlChecker/pulls)/[issue](https://github.com/TrianguloY/UrlChecker/issues/new) titled `{locale} Translation proposal` or by sending the files by email to [TrianguloY](https://github.com/TrianguloY). +This is a small guide for first-time contributors to be able to build and execute this application in Android Studio. +Note that there are several ways to prepare your computer for this purpose, and this may not be the best one for your setup, but it should work in most cases: -For manual translation, there are two independent things to translate: +1. Download Android Studio from [here](https://developer.android.com/studio). +2. Clone this github repository to your local workspace. You can do it from inside Android Studio Itself, or using git directly: `git clone https://github.com/TrianguloY/UrlChecker.git`. +3. Wait until the app is downloaded and parsed. You should wait until all background tasks finish. Usually you will get either a 'ready' notification or a red error. If it's the later try to fix it according to the error message and Internet's help, if you stil can't feel free to create an issue. +4. If not yet, prepare a device emulator from the Tools->Device Manager. You can just follow the instructions in the setup dialog. This step may be automatic when you try to run the app, so if you see an emulator already there, you probably don't need to do anything else. Using your own device for testing is also possible, but it may be more difficult to setup (although, again, Android Studio should provide you with a step-by-step guide). +5. Run the app. If step 3 was completed you should be able to just press the 'play' button (green triangle) at the top. If it is disabled it may say why, if it complains about a missing emulator, setup one using step 4. +6. If everything went according to plan, you should be able to see the app installed in your emulator and be able to run it smoothly. -- **App strings**: the [`strings.xml`](../app/src/main/res/values/strings.xml) file - - Translate all texts between the `` and `` tags. - - Remember to insert a backslash `\` before any apostrophe `'`, or enclose all text in quotes `"` - - Place the translated file in the corresponding `./app/src/main/res/values-{locale}/` folder +## App Architecture -- **Store strings**: the [`title.txt`](../app/src/main/play/listings/en-US/title.txt) [`short-description.txt`](../app/src/main/play/listings/en-US/short-description.txt) and/or [`full-description.txt`](../app/src/main/play/listings/en-US/full-description.txt) files - - Place the translated files in the corresponding `./app/src/main/play/listings/{locale}/` folder +UrlChecker is an Android Application that checks Url links. It is separated into modules. A very basic overview of the codebase is: -Note: if you are unsure the locale prefix of a specific language you can find it [here](https://countrycode.org/). +- Activities: Full activities, like the startup screen, the settings, backup, etc. +- Dialogs: Popup dialogs, same as activities but show the previous app behind, like the main dialog. +- Fragments: Parts of an app that can be placed on different things. Not exactly Android's fragments... +- Modules: Each of the 'parts' that you can individually enable/disable for the main functionality. This is where you probably want to start. +- Services: Custom tabs service. +- Url: Manages the data that the modules use to communicate. +- Utilities: General-purpose methods and classes. +- Views: Custom views. +