From eb7f5e57cc2f0b021e7ad5b4b04f31a50ad527a5 Mon Sep 17 00:00:00 2001 From: Ludy Date: Mon, 7 Jul 2025 10:49:44 +0200 Subject: [PATCH 1/2] docs: restructure documentation paths, update PR template links, and add exception handling guide (#3885) # Description of Changes - **What was changed** - Updated `.github/labeler-config-srvaroa.yml` to match the new `devGuide/.*` patterns instead of the old `HowToAddNewLanguage.md` - Modified `.github/pull_request_template.md` to point to `devGuide/DeveloperGuide.md` and `devGuide/HowToAddNewLanguage.md` for the Developer Guide and translation-tags sections - Updated the SSO link in `README.md` to point to the 'Single Sign-On Configuration' section on docs.stirlingpdf.com instead of the outdated Enterprise Edition page - Changed the relative link in `devGuide/DeveloperGuide.md` to use `../CONTRIBUTING.md` for consistency - Added a new `devGuide/EXCEPTION_HANDLING_GUIDE.md` to document standard exception-handling patterns and internationalisation best practices - Updated `devGuide/README.md` index to reflect the new location and naming conventions for development guides - **Why the change was made** - To centralise all development documentation under a single `devGuide` directory for better organisation and discoverability. - To ensure that GitHub labeler rules and PR templates correctly reference the new file structure. - To introduce a clear, project-wide guide on exception handling, improving consistency across Java, JavaScript, HTML/CSS, and Python components. Closes #3799 --- ## Checklist ### General - [x] I have read the [Contribution Guidelines](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/CONTRIBUTING.md) - [x] I have read the [Stirling-PDF Developer Guide](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/DeveloperGuide.md) (if applicable) - [ ] I have read the [How to add new languages to Stirling-PDF](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/HowToAddNewLanguage.md) (if applicable) - [x] I have performed a self-review of my own code - [x] My changes generate no new warnings ### Documentation - [ ] I have updated relevant docs on [Stirling-PDF's doc repo](https://github.com/Stirling-Tools/Stirling-Tools.github.io/blob/main/docs/) (if functionality has heavily changed) - [ ] I have read the section [Add New Translation Tags](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/HowToAddNewLanguage.md#add-new-translation-tags) (for new translation tags only) ### UI Changes (if applicable) - [ ] Screenshots or videos demonstrating the UI changes are attached (e.g., as comments or direct attachments in the PR) ### Testing (if applicable) - [ ] I have tested my changes locally. Refer to the [Testing Guide](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/DeveloperGuide.md#6-testing) for more details. --- .github/labeler-config-srvaroa.yml | 2 +- .github/pull_request_template.md | 10 +++-- README.md | 2 +- devGuide/DeveloperGuide.md | 2 +- devGuide/EXCEPTION_HANDLING_GUIDE.md | 66 ++++++++++++++++++++++++++++ devGuide/README.md | 2 +- 6 files changed, 76 insertions(+), 8 deletions(-) create mode 100644 devGuide/EXCEPTION_HANDLING_GUIDE.md diff --git a/.github/labeler-config-srvaroa.yml b/.github/labeler-config-srvaroa.yml index f8e66fab4..b2324fbe3 100644 --- a/.github/labeler-config-srvaroa.yml +++ b/.github/labeler-config-srvaroa.yml @@ -115,7 +115,7 @@ labels: - '.editorconfig' - '.pre-commit-config' - '.github/workflows/pre_commit.yml' - - 'HowToAddNewLanguage.md' + - 'devGuide/.*' - label: 'Test' files: diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index da5780860..b909f28e8 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,5 +1,6 @@ # Description of Changes + --- @@ -15,15 +17,15 @@ Closes #(issue_number) ### General - [ ] I have read the [Contribution Guidelines](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/CONTRIBUTING.md) -- [ ] I have read the [Stirling-PDF Developer Guide](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/DeveloperGuide.md) (if applicable) -- [ ] I have read the [How to add new languages to Stirling-PDF](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/HowToAddNewLanguage.md) (if applicable) +- [ ] I have read the [Stirling-PDF Developer Guide](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/DeveloperGuide.md) (if applicable) +- [ ] I have read the [How to add new languages to Stirling-PDF](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/HowToAddNewLanguage.md) (if applicable) - [ ] I have performed a self-review of my own code - [ ] My changes generate no new warnings ### Documentation - [ ] I have updated relevant docs on [Stirling-PDF's doc repo](https://github.com/Stirling-Tools/Stirling-Tools.github.io/blob/main/docs/) (if functionality has heavily changed) -- [ ] I have read the section [Add New Translation Tags](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/HowToAddNewLanguage.md#add-new-translation-tags) (for new translation tags only) +- [ ] I have read the section [Add New Translation Tags](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/HowToAddNewLanguage.md#add-new-translation-tags) (for new translation tags only) ### UI Changes (if applicable) @@ -31,4 +33,4 @@ Closes #(issue_number) ### Testing (if applicable) -- [ ] I have tested my changes locally. Refer to the [Testing Guide](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/DeveloperGuide.md#6-testing) for more details. +- [ ] I have tested my changes locally. Refer to the [Testing Guide](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/DeveloperGuide.md#6-testing) for more details. diff --git a/README.md b/README.md index b7550dfca..807b8ea95 100644 --- a/README.md +++ b/README.md @@ -29,7 +29,7 @@ All documentation available at [https://docs.stirlingpdf.com/](https://docs.stir - API for integration with external scripts - Optional Login and Authentication support (see [here](https://docs.stirlingpdf.com/Advanced%20Configuration/System%20and%20Security) for documentation) - Database Backup and Import (see [here](https://docs.stirlingpdf.com/Advanced%20Configuration/DATABASE) for documentation) -- Enterprise features like SSO see [here](https://docs.stirlingpdf.com/Enterprise%20Edition) +- Enterprise features like SSO (see [here](https://docs.stirlingpdf.com/Advanced%20Configuration/Single%20Sign-On%20Configuration) for documentation) ## PDF Features diff --git a/devGuide/DeveloperGuide.md b/devGuide/DeveloperGuide.md index d2c9ddb2a..c04b66dab 100644 --- a/devGuide/DeveloperGuide.md +++ b/devGuide/DeveloperGuide.md @@ -272,7 +272,7 @@ Important notes: 6. Push your changes to your fork. 7. Submit a pull request to the main repository. -8. See additional [contributing guidelines](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/CONTRIBUTING.md). +8. See additional [contributing guidelines](../CONTRIBUTING.md). When you raise a PR: diff --git a/devGuide/EXCEPTION_HANDLING_GUIDE.md b/devGuide/EXCEPTION_HANDLING_GUIDE.md new file mode 100644 index 000000000..666b70e2b --- /dev/null +++ b/devGuide/EXCEPTION_HANDLING_GUIDE.md @@ -0,0 +1,66 @@ +# Exception Handling Guide + +This guide outlines the common error handling patterns used within Stirling-PDF and provides tips for internationalising error messages. The examples cover the main languages found in the project: Java, JavaScript, HTML/CSS, and a small amount of Python. + +## General Principles + +- **Fail fast and log clearly.** Exceptions should provide enough information for debugging without exposing sensitive data. +- **Use consistent user messages.** Text shown to users must be pulled from the localisation files so that translations are centrally managed. +- **Avoid silent failures.** Always log unexpected errors and provide the user with a helpful message. + +## Java + +Java forms the core of Stirling-PDF. When adding new features or handling errors: + +1. **Create custom exceptions** to represent specific failure cases. This keeps the code self-documenting and easier to handle at higher levels. +2. **Use `try-with-resources`** when working with streams or other closable resources to ensure clean-up even on failure. +3. **Return meaningful HTTP status codes** in controllers by throwing `ResponseStatusException` or using `@ExceptionHandler` methods. +4. **Log with context** using the project’s logging framework. Include identifiers or IDs that help trace the issue. +5. **Internationalise messages** by placing user-facing text in `messages_en_GB.properties` and referencing them with message keys. + +## JavaScript + +On the client side, JavaScript handles form validation and user interactions. + +- Use `try`/`catch` around asynchronous operations (e.g., `fetch`) and display a translated error notice if the call fails. +- Validate input before sending it to the server and provide inline feedback with messages from the translation files. +- Log unexpected errors to the browser console for easier debugging, but avoid revealing sensitive information. + +## HTML & CSS + +HTML templates should reserve a space for displaying error messages. Example pattern: + +```html + +``` + +Use CSS classes (e.g., `.error`) to style the message so it is clearly visible and accessible. Keep the markup simple to ensure screen readers can announce the error correctly. + +## Python + +Python scripts in this project are mainly for utility tasks. Follow these guidelines: + +- Wrap file operations or external calls in `try`/`except` blocks. +- Print or log errors in a consistent format. If the script outputs messages to end users, ensure they are translatable. + +Example: + +```python +try: + perform_task() +except Exception as err: + logger.error("Task failed: %s", err) + print(gettext("task.error")) +``` + +## Internationalisation (i18n) + +All user-visible error strings should be defined in the main translation file (`messages_en_GB.properties`). Other language files will use the same keys. Refer to messages in code rather than hard-coding text. + +When creating new messages: + +1. Add the English phrase to `messages_en_GB.properties`. +2. Reference the message key in your Java, JavaScript, or Python code. +3. Update other localisation files as needed. + +Following these patterns helps keep Stirling-PDF stable, easier to debug, and friendly to users in all supported languages. diff --git a/devGuide/README.md b/devGuide/README.md index 55d8aecee..f58f6e5d1 100644 --- a/devGuide/README.md +++ b/devGuide/README.md @@ -26,4 +26,4 @@ When adding new development documentation: 1. Place technical guides in this `devGuide/` directory 2. Update this index file with a brief description 3. Keep user-facing docs (README, CONTRIBUTING, SECURITY) in the root -4. Follow existing naming conventions (PascalCase for guides) \ No newline at end of file +4. Follow existing naming conventions (PascalCase for guides) From 6cc42ff6d640612284e358b100358208c5272ab3 Mon Sep 17 00:00:00 2001 From: Ludy Date: Mon, 7 Jul 2025 10:50:40 +0200 Subject: [PATCH 2/2] fix(spelling): correct `selectFilter` typo across templates and localization files (#3886) # Description of Changes - **What was changed** - Renamed all occurrences of the misspelled key `selectFillter` to `selectFilter` in HTML templates (`team-details.html`, `adminSettings.html`, `cert-sign.html`) and in every locale properties file under `stirling-pdf/src/main/resources/messages_*.properties`. - Removed obsolete `WorkInProgess` entries from various locale files. - **Why the change was made** To fix a consistent spelling mistake in the UI select placeholder key, ensuring that the label displays correctly and translations resolve properly. --- ## Checklist ### General - [x] I have read the [Contribution Guidelines](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/CONTRIBUTING.md) - [x] I have read the [Stirling-PDF Developer Guide](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/DeveloperGuide.md) (if applicable) - [ ] I have read the [How to add new languages to Stirling-PDF](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/HowToAddNewLanguage.md) (if applicable) - [x] I have performed a self-review of my own code - [x] My changes generate no new warnings ### Documentation - [ ] I have updated relevant docs on [Stirling-PDF's doc repo](https://github.com/Stirling-Tools/Stirling-Tools.github.io/blob/main/docs/) (if functionality has heavily changed) - [ ] I have read the section [Add New Translation Tags](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/HowToAddNewLanguage.md#add-new-translation-tags) (for new translation tags only) ### UI Changes (if applicable) - [ ] Screenshots or videos demonstrating the UI changes are attached (e.g., as comments or direct attachments in the PR) ### Testing (if applicable) - [ ] I have tested my changes locally. Refer to the [Testing Guide](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/DeveloperGuide.md#6-testing) for more details. --- .../resources/templates/accounts/team-details.html | 2 +- .../src/main/resources/messages_ar_AR.properties | 3 +-- .../src/main/resources/messages_az_AZ.properties | 3 +-- .../src/main/resources/messages_bg_BG.properties | 3 +-- .../src/main/resources/messages_bo_CN.properties | 3 +-- .../src/main/resources/messages_ca_CA.properties | 3 +-- .../src/main/resources/messages_cs_CZ.properties | 3 +-- .../src/main/resources/messages_da_DK.properties | 3 +-- .../src/main/resources/messages_de_DE.properties | 3 +-- .../src/main/resources/messages_el_GR.properties | 3 +-- .../src/main/resources/messages_en_GB.properties | 7 +++---- .../src/main/resources/messages_en_US.properties | 3 +-- .../src/main/resources/messages_es_ES.properties | 3 +-- .../src/main/resources/messages_eu_ES.properties | 3 +-- .../src/main/resources/messages_fa_IR.properties | 3 +-- .../src/main/resources/messages_fr_FR.properties | 3 +-- .../src/main/resources/messages_ga_IE.properties | 3 +-- .../src/main/resources/messages_hi_IN.properties | 3 +-- .../src/main/resources/messages_hr_HR.properties | 3 +-- .../src/main/resources/messages_hu_HU.properties | 3 +-- .../src/main/resources/messages_id_ID.properties | 3 +-- .../src/main/resources/messages_it_IT.properties | 3 +-- .../src/main/resources/messages_ja_JP.properties | 3 +-- .../src/main/resources/messages_ko_KR.properties | 3 +-- .../src/main/resources/messages_ml_IN.properties | 3 +-- .../src/main/resources/messages_nl_NL.properties | 3 +-- .../src/main/resources/messages_no_NB.properties | 3 +-- .../src/main/resources/messages_pl_PL.properties | 3 +-- .../src/main/resources/messages_pt_BR.properties | 3 +-- .../src/main/resources/messages_pt_PT.properties | 3 +-- .../src/main/resources/messages_ro_RO.properties | 3 +-- .../src/main/resources/messages_ru_RU.properties | 3 +-- .../src/main/resources/messages_sk_SK.properties | 3 +-- .../src/main/resources/messages_sl_SI.properties | 3 +-- .../src/main/resources/messages_sr_LATN_RS.properties | 3 +-- .../src/main/resources/messages_sv_SE.properties | 3 +-- .../src/main/resources/messages_th_TH.properties | 3 +-- .../src/main/resources/messages_tr_TR.properties | 3 +-- .../src/main/resources/messages_uk_UA.properties | 3 +-- .../src/main/resources/messages_vi_VN.properties | 3 +-- .../src/main/resources/messages_zh_CN.properties | 3 +-- .../src/main/resources/messages_zh_TW.properties | 3 +-- .../src/main/resources/templates/adminSettings.html | 10 +++++----- .../main/resources/templates/security/cert-sign.html | 2 +- 44 files changed, 50 insertions(+), 91 deletions(-) diff --git a/proprietary/src/main/resources/templates/accounts/team-details.html b/proprietary/src/main/resources/templates/accounts/team-details.html index 3fb779bae..bc7d2e533 100644 --- a/proprietary/src/main/resources/templates/accounts/team-details.html +++ b/proprietary/src/main/resources/templates/accounts/team-details.html @@ -168,7 +168,7 @@
- +
@@ -214,7 +214,7 @@
@@ -222,7 +222,7 @@
@@ -279,7 +279,7 @@
@@ -287,7 +287,7 @@
diff --git a/stirling-pdf/src/main/resources/templates/security/cert-sign.html b/stirling-pdf/src/main/resources/templates/security/cert-sign.html index e69c4fa1a..d83f8c249 100644 --- a/stirling-pdf/src/main/resources/templates/security/cert-sign.html +++ b/stirling-pdf/src/main/resources/templates/security/cert-sign.html @@ -28,7 +28,7 @@