From 1a089473349a39e7619fd74160d27890c7d4ba43 Mon Sep 17 00:00:00 2001 From: Adam Monsen Date: Tue, 7 Jul 2026 14:52:05 -0700 Subject: [PATCH 01/11] clarify jira freeze step --- .../src/docs/en/chapters/release/process-step04.adoc | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/fineract-doc/src/docs/en/chapters/release/process-step04.adoc b/fineract-doc/src/docs/en/chapters/release/process-step04.adoc index eeb8f47bc92..015960df0b4 100644 --- a/fineract-doc/src/docs/en/chapters/release/process-step04.adoc +++ b/fineract-doc/src/docs/en/chapters/release/process-step04.adoc @@ -2,7 +2,15 @@ == Description -You first need to close the release in JIRA so that the about to be released version cannot be used as "fixVersion" for new bugs anymore. Go to JIRA "Administer project" page and follow "Versions" in left menu. Table with list of all releases should appear, click on additional menu on the right of your release and choose "Release" option. Submit release date and you're done. +You first need to close the release in JIRA so that the about to be released version cannot be used as "fixVersion" for new bugs anymore. + +https://issues.apache.org/jira/plugins/servlet/project-config/FINERACT/administer-versions?status=released-unreleased[Click this link] or go to JIRA "Administer project" page and follow "Versions" in left menu. + +A form to add new releases and a table with list of all releases should appear. First, create the _next_ release. Enter that version number in the form and click "Add". + +Next, in the "Actions" column in the table, click on ⋯ (three horizontal dots menu) to the right of release {version}. Choose "Release". Enter the current date (doesn't need to be the date the release is acutally announced). + +TIP: For the "Unresolved Issues" radio button: If unresolved issues block the release, ignore them and proceed. If they'll be part of another release, move them to that version. == Gradle Task From c42d63c6c52e2260044bbe39a7bd233ec9780dab Mon Sep 17 00:00:00 2001 From: Adam Monsen Date: Fri, 10 Jul 2026 10:50:41 -0700 Subject: [PATCH 02/11] include JIRA issue handling guidance --- .github/pull_request_template.md | 1 + CONTRIBUTING.md | 5 +++-- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index e9628d8201a..00af4e3ec01 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -12,5 +12,6 @@ Please make sure these boxes are checked before submitting your pull request - t - [ ] Follow our [coding conventions](https://cwiki.apache.org/confluence/display/FINERACT/Coding+Conventions). - [ ] Add required Swagger annotation and update API documentation at fineract-provider/src/main/resources/static/legacy-docs/apiLive.htm with details of any API changes - [ ] [This PR must not be a "code dump"](https://cwiki.apache.org/confluence/display/FINERACT/Pull+Request+Size+Limit). Large changes can be made in a branch, with assistance. Ask for help on the [developer mailing list](https://fineract.apache.org/#contribute). +- [ ] If merging this PR resolves a JIRA issue, I will mark that issue as resolved and set "Fix Version/s" appropriately. Your assigned reviewer(s) will follow our [guidelines for code reviews](https://cwiki.apache.org/confluence/display/FINERACT/Code+Review+Guide). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 627bfd616ba..1c7d9064f3e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -298,8 +298,8 @@ Our `ClasspathHellDuplicatesCheckRuleTest` detects classes that appear in more t ### Pull Requests -We request that your commit message includes a FINERACT JIRA issue and a one-liner that describes the changes. -Start with an upper case imperative verb (not past form), and a short but concise clear description. (E.g. "FINERACT-821: Add enforced HideUtilityClassConstructor checkstyle"). +Your PR title must include a JIRA issue and a one-liner that describes the changes. +Start your one-liner after the JIRA issue id. Use an upper case present-tense imperative verb and a short but concise clear description. (E.g. "FINERACT-821: Add enforced HideUtilityClassConstructor checkstyle"). If your PR is failing to pass our CI build due to a test failure, then: @@ -337,6 +337,7 @@ We have an automated bot which marks pull requests as "stale" after a while, and After PR review and passing CI build, a committer will merge your PR branch into our primary integration branch, `develop`, either locally or on GitHub using "Merge pull request - Create a merge commit" (not "Squash and merge" and not "Rebase and merge"). +If merging the PR resolved a JIRA issue, mark that issue as resolved and set "Fix Version/s" to the next unreleased version. These fix versions only apply to the `apache/fineract` repository. Other repositories should set "Fix Version/s" to "Unknown". ### Signing Your Commits From 9980121117bf41720104aae668dd0a6c61890e10 Mon Sep 17 00:00:00 2001 From: Adam Monsen Date: Fri, 10 Jul 2026 11:10:47 -0700 Subject: [PATCH 03/11] =?UTF-8?q?Modernize=20example=20commands:=20git=20c?= =?UTF-8?q?heckout=20=E2=86=92=20git=20switch?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Git checkout is confusing. It does too many things. The relatively new `git switch` (for switching branches) is clearer. Easier to teach, learn, and remember. Yes there's some muscle memory to update, that's OK. And yes the very conservative git-switch(1) and git-restore(1) manual pages say they are experimental, they are more or less canon by now. More on `git checkout` vs. `git switch` and `git restore`: * https://www.infoq.com/news/2019/08/git-2-23-switch-restore/ * https://stackoverflow.com/questions/57265785/whats-the-difference-between-git-switch-and-git-checkout-branch --- .../src/main/resources/instructions/step13.txt.ftl | 2 +- fineract-command/README.md | 2 +- .../contributor/pages/take-your-first-steps.adoc | 10 +++++----- .../architecture/api-backward-compatibility.adoc | 4 ++-- .../src/docs/en/chapters/release/process-step03.adoc | 2 +- .../src/docs/en/chapters/release/process-step05.adoc | 2 +- .../src/docs/en/chapters/release/process-step06.adoc | 2 +- .../src/docs/en/chapters/release/process-step13.adoc | 2 +- 8 files changed, 13 insertions(+), 13 deletions(-) diff --git a/buildSrc/src/main/resources/instructions/step13.txt.ftl b/buildSrc/src/main/resources/instructions/step13.txt.ftl index db0b697126e..def00e04b0e 100644 --- a/buildSrc/src/main/resources/instructions/step13.txt.ftl +++ b/buildSrc/src/main/resources/instructions/step13.txt.ftl @@ -25,7 +25,7 @@ As discussed in https://issues.apache.org/jira/browse/FINERACT-1154, now that everything is final, please do the following to remove the release branch (and just keep the tag), and make sure that everything on the release tag is merged to develop and that e.g. git describe works: ->> git checkout develop +>> git switch develop >> git merge release/${project['fineract.release.version']} >> git push origin develop >> git branch -D release/${project['fineract.release.version']} diff --git a/fineract-command/README.md b/fineract-command/README.md index f386996ee9b..b47d88f8b75 100644 --- a/fineract-command/README.md +++ b/fineract-command/README.md @@ -114,7 +114,7 @@ You can try it out with the following instructions (it's still in a private repo ``` git clone git@github.com:vidakovic/fineract.git cd fineract -git checkout feature/FINERACT-2169 +git switch feature/FINERACT-2169 ./gradlew :fineract-command:build ./gradlew :fineract-command:jmh ``` diff --git a/fineract-doc/modules/contributor/pages/take-your-first-steps.adoc b/fineract-doc/modules/contributor/pages/take-your-first-steps.adoc index 235815f8f6c..bc858a7e2f3 100644 --- a/fineract-doc/modules/contributor/pages/take-your-first-steps.adoc +++ b/fineract-doc/modules/contributor/pages/take-your-first-steps.adoc @@ -16,7 +16,7 @@ Develop currently represents work toward Apache Fineract 1.0.0. Please submit al [source] ---- -git checkout develop +git switch develop ---- === Use short branch names @@ -24,7 +24,7 @@ Branches used when submitting pull requests should preferably be named according [source] ---- -git checkout -b [topic] +git switch -c [topic] ---- === Pull in changes @@ -36,7 +36,7 @@ To pull in upstream changes from repository you forked: [source] ---- -git checkout develop +git switch develop git fetch upstream git merge upstream/develop ---- @@ -55,7 +55,7 @@ After you pulled all changes from upstream you need to rebase your topic branch [source] ---- -git checkout [topic] +git switch [topic] git rebase develop ---- @@ -65,4 +65,4 @@ If you are ready push your topic branch to your GitHub account: git push origin [topic] ---- -Now thats your changes have been pushed to your github account, follow the steps and guidelines found xref:submitting-a-pull-request.adoc[here] to submit your pull request from your git account to fineract. \ No newline at end of file +Now thats your changes have been pushed to your github account, follow the steps and guidelines found xref:submitting-a-pull-request.adoc[here] to submit your pull request from your git account to fineract. diff --git a/fineract-doc/src/docs/en/chapters/architecture/api-backward-compatibility.adoc b/fineract-doc/src/docs/en/chapters/architecture/api-backward-compatibility.adoc index 59eb81c4f24..11d49ccf3e4 100644 --- a/fineract-doc/src/docs/en/chapters/architecture/api-backward-compatibility.adoc +++ b/fineract-doc/src/docs/en/chapters/architecture/api-backward-compatibility.adoc @@ -112,10 +112,10 @@ To run the check locally, you need a baseline spec to compare against: ---- # 1. Generate the baseline from develop git stash -git checkout develop +git switch develop ./gradlew :fineract-provider:resolve --no-daemon cp fineract-provider/build/resources/main/static/fineract.json /tmp/baseline.json -git checkout - +git switch - git stash pop # 2. Generate your current spec and compare diff --git a/fineract-doc/src/docs/en/chapters/release/process-step03.adoc b/fineract-doc/src/docs/en/chapters/release/process-step03.adoc index 1db633dd92d..92b179a8b6a 100644 --- a/fineract-doc/src/docs/en/chapters/release/process-step03.adoc +++ b/fineract-doc/src/docs/en/chapters/release/process-step03.adoc @@ -26,7 +26,7 @@ git log <1> + [source,bash,subs="attributes+,+macros"] ---- -git checkout -b release/{revnumber} +git switch -c release/{revnumber} ---- 4. Push new branch to Apache Fineract repository diff --git a/fineract-doc/src/docs/en/chapters/release/process-step05.adoc b/fineract-doc/src/docs/en/chapters/release/process-step05.adoc index 9a7a0b77c3c..2ff08ca743c 100644 --- a/fineract-doc/src/docs/en/chapters/release/process-step05.adoc +++ b/fineract-doc/src/docs/en/chapters/release/process-step05.adoc @@ -6,7 +6,7 @@ Next, you create a git tag from the HEAD of the release's git branch. [source,bash,subs="attributes+,+macros"] ---- -git checkout -b release/{revnumber} <1> +git switch -c release/{revnumber} <1> git tag -a {revnumber} -m "Fineract {revnumber} release" -s <2> git push origin tag {revnumber} ---- diff --git a/fineract-doc/src/docs/en/chapters/release/process-step06.adoc b/fineract-doc/src/docs/en/chapters/release/process-step06.adoc index 5cca8334efe..35814069676 100644 --- a/fineract-doc/src/docs/en/chapters/release/process-step06.adoc +++ b/fineract-doc/src/docs/en/chapters/release/process-step06.adoc @@ -23,7 +23,7 @@ cd /fineract-release-preparations tar -xvzf path/to/apache-fineract-src-{revnumber}.tar.gz git clone git@github.com:apache/fineract.git cd fineract/ -git checkout tags/{revnumber} +git switch --detach tags/{revnumber} cd .. diff -r fineract apache-fineract-src-{revnumber} ---- diff --git a/fineract-doc/src/docs/en/chapters/release/process-step13.adoc b/fineract-doc/src/docs/en/chapters/release/process-step13.adoc index e56c43449bb..2c3130c2f7d 100644 --- a/fineract-doc/src/docs/en/chapters/release/process-step13.adoc +++ b/fineract-doc/src/docs/en/chapters/release/process-step13.adoc @@ -6,7 +6,7 @@ As discussed in https://issues.apache.org/jira/browse/FINERACT-1154[FINERACT-115 [source,bash,subs="attributes+,+macros"] ---- -git checkout develop +git switch develop git merge release/{revnumber} <1> git push origin develop git branch -D release/{revnumber} From 82c98726c9f06b3b26ebddf1873d97156552b129 Mon Sep 17 00:00:00 2001 From: Adam Monsen Date: Fri, 10 Jul 2026 13:39:36 -0700 Subject: [PATCH 04/11] don't descend custom/ dirs w/o build.gradle MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This avoids an issue running `./gradlew generateLicenseReport` multiple times (something I'm having to do while working on the 1.15.0 release). The issue I was seeing was: Error while evaluating property 'classpath' of task ':custom:generateLicenseReport'. java.util.ConcurrentModificationException (no error message) Claude identified the problem and created the patch (model=Sonnet 5, effort=High). Claude said: This is a runaway self-amplifying bug in the dynamic "custom module" project-discovery logic, not a transient Gradle glitch. The chain of events: 1. build.gradle:280-282 applies com.github.jk1.dependency-license-report to every project (allprojects) and sets licenseReport.outputDir = "$projectDir/licenses". 2. settings.gradle:90-99 dynamically walks custom/// and includes each combo as a project — but only excludes directories named build or docker. It does not exclude licenses. 3. Because past runs already wrote license report output (including unpacked per-jar license files) into custom/licenses/..., custom/acme/licenses/..., etc., those output folders now look like valid company/category/module paths to the settings.gradle scanner. Gradle happily registers hundreds of bogus phantom projects like :custom:licenses:commons-lang3-3.20.0.jar:META-INF and :custom:acme:licenses:spring-core-6.2.18.jar. 4. build.gradle:378-392 does the same directory walk and applies the full java plugin to every one of those phantom projects via configure(project.fineractJavaProjects) { apply plugin: 'java' ... }. 5. Since license-report is on allprojects, each phantom project gets its own generateLicenseReport task whose output again lands at $projectDir/licenses — nesting the mess one level deeper every time the task runs (I found custom/acme/licenses/licenses/licenses on disk — 3 generations deep already). I confirmed this directly: running ./gradlew generateLicenseReport --parallel just now produced 812 actionable tasks, most named after individual jar files (:custom:licenses:commons-lang3-3.20.0.jar:META-INF:generateLicenseReport, etc.) — these should not exist as Gradle projects at all. With org.gradle.parallel=true set in gradle.properties, Gradle executes hundreds of these bogus generateLicenseReport tasks concurrently. At that scale, a thread-safety bug (in Gradle's dependency-resolution internals or the gradle-license-report 2.9 plugin itself) gets tripped, surfacing as the ConcurrentModificationException on the classpath property — it's a race condition, which is why running the single task in isolation just now succeeded fine. I verified these licenses directories under custom/ are untracked/gitignored build output (not committed), so deleting them is safe. Proposed fix (two parts): 1. Cleanup: delete all the runaway custom/**/licenses directories so the phantom projects disappear. 2. Root-cause patch: harden the eachDir walks in settings.gradle and build.gradle to only treat a directory as a real custom module if it actually contains a build.gradle file (robust against any future output-directory name), or at minimum also exclude licenses. I reviewed and tested the code and it all LGTM, but just a heads up that I'm not an expert with Gradle nor the Fineract build. I don't need this fix to release 1.15.0, I can just manually do this for now: git clean -fdx custom --- build.gradle | 2 +- custom/docker/build.gradle | 2 +- settings.gradle | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/build.gradle b/build.gradle index fe693346622..20ceead16dd 100644 --- a/build.gradle +++ b/build.gradle @@ -382,7 +382,7 @@ file("${rootDir}/custom").eachDir { companyDir -> file("${rootDir}/custom/${companyDir.name}").eachDir { categoryDir -> if('build' != categoryDir.name) { file("${rootDir}/custom/${companyDir.name}/${categoryDir.name}").eachDir { moduleDir -> - if('build' != moduleDir.name) { + if('build' != moduleDir.name && file("${moduleDir}/build.gradle").exists()) { project.fineractJavaProjects.add(project(":custom:${companyDir.name}:${categoryDir.name}:${moduleDir.name}")) project.fineractCustomProjects.add(project(":custom:${companyDir.name}:${categoryDir.name}:${moduleDir.name}")) } diff --git a/custom/docker/build.gradle b/custom/docker/build.gradle index 4ed3f7a96bd..ad505fa6fb6 100644 --- a/custom/docker/build.gradle +++ b/custom/docker/build.gradle @@ -66,7 +66,7 @@ jib { file("${rootDir}/custom/${companyDir.name}").eachDir { categoryDir -> if('build' != categoryDir.name) { file("${rootDir}/custom/${companyDir.name}/${categoryDir.name}").eachDir { moduleDir -> - if('build' != moduleDir.name) { + if('build' != moduleDir.name && file("${moduleDir}/build.gradle").exists()) { implementation project(":custom:${companyDir.name}:${categoryDir.name}:${moduleDir.name}") } } diff --git a/settings.gradle b/settings.gradle index cc45f2797ae..3de7fbf1365 100644 --- a/settings.gradle +++ b/settings.gradle @@ -91,7 +91,7 @@ file("${rootDir}/custom").eachDir { companyDir -> file("${rootDir}/custom/${companyDir.name}").eachDir { categoryDir -> if('build' != categoryDir.name) { file("${rootDir}/custom/${companyDir.name}/${categoryDir.name}").eachDir { moduleDir -> - if('build' != moduleDir.name) { + if('build' != moduleDir.name && file("${moduleDir}/build.gradle").exists()) { include ":custom:${companyDir.name}:${categoryDir.name}:${moduleDir.name}" } } From c501070531d051df08b031ce3fabd48a95ce4515 Mon Sep 17 00:00:00 2001 From: Adam Monsen Date: Fri, 10 Jul 2026 15:53:29 -0700 Subject: [PATCH 05/11] clarify successful src tarball diff run and fix the reference to "what you will ask the community to do in..." --- .../en/chapters/release/process-step06.adoc | 36 ++++++++++++++++++- 1 file changed, 35 insertions(+), 1 deletion(-) diff --git a/fineract-doc/src/docs/en/chapters/release/process-step06.adoc b/fineract-doc/src/docs/en/chapters/release/process-step06.adoc index 35814069676..280186d0cc7 100644 --- a/fineract-doc/src/docs/en/chapters/release/process-step06.adoc +++ b/fineract-doc/src/docs/en/chapters/release/process-step06.adoc @@ -28,7 +28,41 @@ cd .. diff -r fineract apache-fineract-src-{revnumber} ---- -Make sure the code compiles and tests pass on the uncompressed source. You should at the very least do exactly what you will ask the community to do in <>. +The diff won't be perfectly clean... some things are excluded from the source tarball on purpose. If you see something like this, it's OK to proceed: + +[source,text] +---- +Only in fineract: .atr-rat-excludes-bin.txt +Only in fineract: .atr-rat-excludes-src.txt +Only in fineract: .dockerignore +Only in fineract/fineract-branch/src/test/java: .gitkeep +Only in fineract/fineract-branch/src/test/resources: .gitkeep +Only in fineract/fineract-client/src/main/resources: .gitkeep +Only in fineract/fineract-core/src/main/java/org/apache/fineract/infrastructure/businessdate/validation: .gitkeep +Only in fineract/fineract-core/src/test/java: .gitkeep +Only in fineract/fineract-core/src/test/resources: .gitkeep +Only in fineract/fineract-doc/src/resources/fonts: .gitkeep +Only in fineract/fineract-doc/src/resources/themes/fineract: .gitkeep +Only in fineract/fineract-investor/src/test/java: .gitkeep +Only in fineract/fineract-investor/src/test/resources: .gitkeep +Only in fineract/fineract-loan/src/test/java: .gitkeep +Only in fineract/fineract-loan/src/test/resources: .gitkeep +Only in fineract: .git +Only in fineract: .github +Only in fineract: .gitignore +Only in apache-fineract-src-1.15.0/integration-tests/src: integrationTest +Only in apache-fineract-src-1.15.0: LICENSE +Only in fineract: LICENSE_RELEASE +Only in fineract: LICENSE_SOURCE +Only in apache-fineract-src-1.15.0: NOTICE +Only in fineract: NOTICE_RELEASE +Only in fineract: NOTICE_SOURCE +Only in apache-fineract-src-1.15.0: .rat-excludes +Only in apache-fineract-src-1.15.0: test-results +Only in fineract: .theia +---- + +Make sure the code compiles and tests pass on the uncompressed source. You should at the very least do exactly what you will ask the community to do in <>. Ideally you'd build code and docs and run every possible test and check, but https://github.com/apache/fineract/actions[running everything has complex dependencies, caches, and takes many hours]. It is rarely done in practice offline / local / on developer machines. But please, go ahead and run the test and doc tasks, and more! Grab a cup of coffee and run everything you can. See the various builds in `.github/workflows/` and try the same things on your own. We should all hammer on a release candidate as much as we can to see if it breaks and fix it if so. All that of course improves our final release. From 81035c7542b496a114d91d51739f05b122740cc2 Mon Sep 17 00:00:00 2001 From: Adam Monsen Date: Fri, 10 Jul 2026 16:23:52 -0700 Subject: [PATCH 06/11] improve ATR rc staging instructions --- fineract-doc/src/docs/en/chapters/release/process-step08.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fineract-doc/src/docs/en/chapters/release/process-step08.adoc b/fineract-doc/src/docs/en/chapters/release/process-step08.adoc index 41cddef413e..8fb2dae8b33 100644 --- a/fineract-doc/src/docs/en/chapters/release/process-step08.adoc +++ b/fineract-doc/src/docs/en/chapters/release/process-step08.adoc @@ -13,7 +13,7 @@ Next we'll stage the release candidate. Create a new folder and add these files: These files (or "artifacts") comprise the release candidate. -First, upload these files to https://release-test.apache.org/compose/fineract/{revnumber}. This tool will initiate automated checks on the files. We'll come back to those in next step and ensure they pass. +First, upload these files to https://release-test.apache.org/compose/fineract/{revnumber}. The `rsync` method seems to work best. After the upload completes, automated checks will run. We'll come back to those in next step and ensure they pass. Next, upload these files to https://www.apache.org/legal/release-policy.html#stage[ASF's distribution dev/staging area] like so: From 35ca22eaa12a6ea615066036d55245dfeea9f36a Mon Sep 17 00:00:00 2001 From: Adam Monsen Date: Fri, 10 Jul 2026 18:19:24 -0700 Subject: [PATCH 07/11] fix two aspects of the release tag 1. Signing is no longer optional. 2. Might be better to wait to push the tag until just before vote. --- .../src/docs/en/chapters/release/process-step05.adoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/fineract-doc/src/docs/en/chapters/release/process-step05.adoc b/fineract-doc/src/docs/en/chapters/release/process-step05.adoc index 2ff08ca743c..49a66d416d2 100644 --- a/fineract-doc/src/docs/en/chapters/release/process-step05.adoc +++ b/fineract-doc/src/docs/en/chapters/release/process-step05.adoc @@ -7,11 +7,11 @@ Next, you create a git tag from the HEAD of the release's git branch. [source,bash,subs="attributes+,+macros"] ---- git switch -c release/{revnumber} <1> -git tag -a {revnumber} -m "Fineract {revnumber} release" -s <2> -git push origin tag {revnumber} +git tag -a {revnumber} -m "Fineract {revnumber} release" -s +git push origin tag {revnumber} <2> ---- <1> Ensure all tests pass for this commit both in CI and locally. -<2> `-s` is optional but recommended: GPG signatures on tags are useful for trust and integrity. +<2> You may opt to wait to push the tag until just before <>. By that time you'll be done with <>, so it's less likely you'd need to try to move the tag. Git tags are meant to be immutable and they tend to spread like viruses. Moving them can be painful or tricky. CAUTION: It is important to create so called annotated tags (vs. lightweight) for releases. From b400dd0494c2fa8c8faca4d162ac10cc20dd9214 Mon Sep 17 00:00:00 2001 From: Adam Monsen Date: Fri, 10 Jul 2026 18:23:54 -0700 Subject: [PATCH 08/11] add PR log message tips things changed a bit since FSIP-7 --- CONTRIBUTING.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1c7d9064f3e..7f9a87c8d3a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -320,6 +320,10 @@ Each commit should be reviewable and logically coherent. Add detail and context as necessary in commit log messages to communicate not only *what* you changed, but *why*, including summaries of discussions leading to the changes, ideas/plans for future changes, etc. Keep the *what* simple: Use the summary (first line) and let the diff otherwise speak for itself. +If your PR is a single commit, use the PR title verbatim in the first line of the commit log message. Add as much detail as you want in the commit log body. + +If your PR is multiple commits, use the first line of the commit log message to summarize changes specific to that commit (using present-tense imperative language, e.g. _update release signing gpg guidance_). You may include the JIRA issue id in the first line or somewhere in the commit log body. + Contributors: squash, rebase, and force-push your PR branches as you see fit. You might, for example, rebase on top of `develop`. You might also squash several commits with code formatting / whitespace fixes, but keep separate commits for code changes affecting functionality. From d88b16ce20e9e0c15af40aaf2f492c0d71fc9fd1 Mon Sep 17 00:00:00 2001 From: Adam Monsen Date: Fri, 10 Jul 2026 19:16:13 -0700 Subject: [PATCH 09/11] don't use ATR auto-publish yet maybe we will once it moves to beta or GA --- fineract-doc/src/docs/en/chapters/release/process-step10.adoc | 2 ++ 1 file changed, 2 insertions(+) diff --git a/fineract-doc/src/docs/en/chapters/release/process-step10.adoc b/fineract-doc/src/docs/en/chapters/release/process-step10.adoc index c3c081ae257..e105bf12a41 100644 --- a/fineract-doc/src/docs/en/chapters/release/process-step10.adoc +++ b/fineract-doc/src/docs/en/chapters/release/process-step10.adoc @@ -4,6 +4,8 @@ Initiate voting with https://release-test.apache.org[the ATR (ASF Trusted Releases) tool]. +Disable "Automatically publish to SVN when this vote resolves". + == Gradle Task .Command From 54d8416ec6f82922f6f48ace902ccd0e03b57939 Mon Sep 17 00:00:00 2001 From: Adam Monsen Date: Mon, 13 Jul 2026 08:56:21 -0700 Subject: [PATCH 10/11] consolidate dev env prerequisites and fix a few mistakes --- README.md | 7 ++----- .../src/docs/en/chapters/development/git.adoc | 2 +- .../src/docs/en/chapters/development/gpg.adoc | 12 +++++++++--- .../src/docs/en/chapters/development/gradle.adoc | 2 +- .../src/docs/en/chapters/development/index.adoc | 6 +++++- .../docs/en/chapters/development/tools-sdkman.adoc | 2 +- .../docs/en/chapters/release/configuration-gpg.adoc | 7 ++++++- 7 files changed, 25 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index b8e5cdca4f1..064fa9b69aa 100644 --- a/README.md +++ b/README.md @@ -29,11 +29,8 @@ In the moment you get started writing code, please consult our [CONTRIBUTING](CO REQUIREMENTS ============ -* 16GB RAM and 8 core CPU (minimum hardware for running Fineract -- development and testing may require more) -* PostgreSQL >= 18.0 ([support for other backend databases is deprecated](https://cwiki.apache.org/confluence/display/FINERACT/FSIP-9%3A+Standardize+on+PostgreSQL)) -* Java >= 21 (Azul Zulu JVM is tested by our CI on GitHub Actions) -Tomcat (min. v10) is only needed if you wish to deploy the Fineract WAR to a separate external servlet container. You do not need to install Tomcat to run Fineract. We recommend the use of the self-contained JAR, which transparently embeds a servlet container using Spring Boot. +See [Fineract Development Environment](https://fineract.apache.org/docs/current/#_fineract_development_environment) in the docs for hardware, software, and tool prerequisites and recommendations. SECURITY @@ -60,7 +57,7 @@ Follow these steps to quickly set up and run Apache Fineract locally. ### Prerequisites -- Java 21 or higher (Azul Zulu is recommended) +- [Java JDK](https://fineract.apache.org/docs/current/#_fineract_development_environment) - PostgreSQL running locally, listening on port 5432 with proper permissions (see [below](#database-and-tables) for how to run PostgreSQL in Docker) ```bash diff --git a/fineract-doc/src/docs/en/chapters/development/git.adoc b/fineract-doc/src/docs/en/chapters/development/git.adoc index 1b7a1feefc6..3c09829cb61 100644 --- a/fineract-doc/src/docs/en/chapters/development/git.adoc +++ b/fineract-doc/src/docs/en/chapters/development/git.adoc @@ -1,3 +1,3 @@ = Git -TBD \ No newline at end of file +Version 2.23 or later (supporting `git switch` and `git restore`). diff --git a/fineract-doc/src/docs/en/chapters/development/gpg.adoc b/fineract-doc/src/docs/en/chapters/development/gpg.adoc index 8c7e4edeaac..af9e7069386 100644 --- a/fineract-doc/src/docs/en/chapters/development/gpg.adoc +++ b/fineract-doc/src/docs/en/chapters/development/gpg.adoc @@ -1,7 +1,13 @@ -= GPG += GnuPG -TBD +GNU Privacy Guard is used for signing commits and releases and for verifying those signatures. Any https://gnupg.org/download/#end-of-life[non-EOL v2 release of GnuPG] should work. + +See <> for help generating keys. == Committers -Please make sure to provide your GPG fingerprint in your Apache committer profile at https://id.apache.org. +Provide your public key fingerprint in your Apache committer profile at https://id.apache.org. + +== PMC members + +Include your public key in https://downloads.apache.org/fineract/KEYS[our KEYS file]. diff --git a/fineract-doc/src/docs/en/chapters/development/gradle.adoc b/fineract-doc/src/docs/en/chapters/development/gradle.adoc index 2d4321536c7..cd852fdd488 100644 --- a/fineract-doc/src/docs/en/chapters/development/gradle.adoc +++ b/fineract-doc/src/docs/en/chapters/development/gradle.adoc @@ -1,3 +1,3 @@ = Gradle -TBD \ No newline at end of file +The https://docs.gradle.org/current/userguide/gradle_wrapper.html[Gradle Wrapper] included with Fineract will automatically run the correct version of Gradle. diff --git a/fineract-doc/src/docs/en/chapters/development/index.adoc b/fineract-doc/src/docs/en/chapters/development/index.adoc index 51d0adbbff0..4b158d2a2c9 100644 --- a/fineract-doc/src/docs/en/chapters/development/index.adoc +++ b/fineract-doc/src/docs/en/chapters/development/index.adoc @@ -1,6 +1,10 @@ = Fineract Development Environment -TBD +* 16GB RAM and 8 core CPU (minimum hardware for running Fineract -- development and testing may require more) +* PostgreSQL >= 18.0 (https://cwiki.apache.org/confluence/display/FINERACT/FSIP-9%3A+Standardize+on+PostgreSQL[support for other backend databases is deprecated]) +* Java >= 21 (https://www.azul.com/downloads/?package=jdk#zulu[Azul Zulu JVM] is tested by our CI on GitHub Actions) + +Tomcat (min. v10) is only needed if you wish to deploy the Fineract WAR to a separate external servlet container. You do not need to install Tomcat to run Fineract. We recommend the use of the self-contained JAR, which transparently embeds a servlet container using Spring Boot. include::git.adoc[leveloffset=+1] diff --git a/fineract-doc/src/docs/en/chapters/development/tools-sdkman.adoc b/fineract-doc/src/docs/en/chapters/development/tools-sdkman.adoc index d34d1a8a5aa..00b488e68f2 100644 --- a/fineract-doc/src/docs/en/chapters/development/tools-sdkman.adoc +++ b/fineract-doc/src/docs/en/chapters/development/tools-sdkman.adoc @@ -1,6 +1,6 @@ = SDKMAN -We recommend using SKDMAN to manage the following developer tools: +We recommend using SDKMAN to manage the following developer tools: - JDK - Spring Boot CLI diff --git a/fineract-doc/src/docs/en/chapters/release/configuration-gpg.adoc b/fineract-doc/src/docs/en/chapters/release/configuration-gpg.adoc index 4774cce9a84..f0e66b6f2bf 100644 --- a/fineract-doc/src/docs/en/chapters/release/configuration-gpg.adoc +++ b/fineract-doc/src/docs/en/chapters/release/configuration-gpg.adoc @@ -1,4 +1,4 @@ -= GPG += Signing releases Generate GPG key pairs if you don't already have them and publish them. Please use your Apache email address when creating your GPG keypair. If you already have configured GPG and associated your keypair with a non-Apache email address then please consider creating a separate one just for all things related to Fineract (or Apache in general). @@ -224,3 +224,8 @@ gXXeWjafxBmHT1cM8hoBZBYzgTu9nK5UnllWunfaHXiCBG4oQQ== =85/F -----END PGP PUBLIC KEY BLOCK----- ---- + +See also: + +* https://infra.apache.org/release-signing.html[Signing Releases] +* https://infra.apache.org/openpgp.html[Cryptography with OpenPGP] From a0e1a414b2630ba2fc53fa59ffbabb21e8489259 Mon Sep 17 00:00:00 2001 From: Adam Monsen Date: Mon, 13 Jul 2026 09:19:42 -0700 Subject: [PATCH 11/11] README: point to bleeding edge for up-to-date dev env info And point to stable docs where it seems to make sense to do so. * use "docs/develop" for docs built recently from the develop branch * use "docs/stable" for the latest stable release docs --- README.md | 16 ++++++++-------- fineract-doc/src/docs/en/colophon.adoc | 6 ++++++ 2 files changed, 14 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 064fa9b69aa..3aa136a9b61 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ flexible, extensible foundation for a wide range of financial services. By making robust banking technology openly available, it lowers barriers for institutions and innovators to reach underserved and unbanked populations. -Have a look at the [documentation](https://fineract.apache.org/docs/current), the [wiki](https://cwiki.apache.org/confluence/display/FINERACT) or at the [FAQ](https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=91554327), if this README does not answer what you are looking for. +Have a look at the [documentation](https://fineract.apache.org/docs/stable), the [wiki](https://cwiki.apache.org/confluence/display/FINERACT) or at the [FAQ](https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=91554327), if this README does not answer what you are looking for. COMMUNITY @@ -30,7 +30,7 @@ In the moment you get started writing code, please consult our [CONTRIBUTING](CO REQUIREMENTS ============ -See [Fineract Development Environment](https://fineract.apache.org/docs/current/#_fineract_development_environment) in the docs for hardware, software, and tool prerequisites and recommendations. +See [Fineract Development Environment](https://fineract.apache.org/docs/develop/#_fineract_development_environment) in the docs for hardware, software, and tool prerequisites and recommendations. SECURITY @@ -39,7 +39,7 @@ For a list of known vulnerabilities, see [Apache Fineract Security Reports](http If you believe you have found a new vulnerability, [let us know privately](https://fineract.apache.org/#contribute). -For details about security during development and deployment, see the documentation [here](https://fineract.apache.org/docs/current/#_security). +For details about security during development and deployment, see the documentation [here](https://fineract.apache.org/docs/stable/#_security). PRIVATE FORKS ============ @@ -57,7 +57,7 @@ Follow these steps to quickly set up and run Apache Fineract locally. ### Prerequisites -- [Java JDK](https://fineract.apache.org/docs/current/#_fineract_development_environment) +- [Java JDK](https://fineract.apache.org/docs/develop/#_fineract_development_environment) - PostgreSQL running locally, listening on port 5432 with proper permissions (see [below](#database-and-tables) for how to run PostgreSQL in Docker) ```bash @@ -112,7 +112,7 @@ Expected response for fresh instance: How to run for production --- -Running Fineract _just to try it out_ is relatively easy. If you intend to use it _in a production environment_, be aware that a proper deployment can be complex, costly, and time-consuming. Considerations include: Security, privacy, compliance, performance, service availability, backups, and more. **The Fineract project does not provide a comprehensive guide for deploying Fineract in production.** You might need skills in enterprise Java applications and more. Alternatively, you could pay a vendor for Fineract deployment and maintenance. You will find tips and tricks for [deploying](https://fineract.apache.org/docs/current/#_deployment) and [securing](https://fineract.apache.org/docs/current/#_securing_fineract) Fineract in our official documentation. +Running Fineract _just to try it out_ is relatively easy. If you intend to use it _in a production environment_, be aware that a proper deployment can be complex, costly, and time-consuming. Considerations include: Security, privacy, compliance, performance, service availability, backups, and more. **The Fineract project does not provide a comprehensive guide for deploying Fineract in production.** You might need skills in enterprise Java applications and more. Alternatively, you could pay a vendor for Fineract deployment and maintenance. You will find tips and tricks for [deploying](https://fineract.apache.org/docs/stable/#_deployment) and [securing](https://fineract.apache.org/docs/stable/#_securing_fineract) Fineract in our official documentation. How to build the JAR file @@ -329,7 +329,7 @@ Kafka support is also disabled by default. In `docker-compose-postgresql-kafka.y During the development Fineract was tested with PLAINTEXT Kafka brokers without authentication and with AWS MSK using IAM authentication. The extra [JAR file](https://github.com/aws/aws-msk-iam-auth/releases) required for IAM authentication is already added to the classpath. An example MSK setup can be found in `docker-compose-postgresql-kafka-msk.yml`. -The full list of supported Kafka related properties is documented in the [Fineract Platform documentation](https://fineract.apache.org/docs/current/). +The full list of supported Kafka related properties is documented in the [Fineract Platform documentation](https://fineract.apache.org/docs/stable/). DATABASE AND TABLES @@ -392,7 +392,7 @@ NOTE: We keep backwards compatibility until one of the next releases to ensure t RELEASES ============ -[Official releases](https://fineract.apache.org/#downloads) are created quarterly, at the end of each quarter. Our [documented release procedure](https://fineract.apache.org/docs/current/#_releases) follows the [ASF release policy](https://www.apache.org/legal/release-policy.html). +[Official releases](https://fineract.apache.org/#downloads) are created quarterly, at the end of each quarter. Our [documented release procedure](https://fineract.apache.org/docs/develop/#_releases) follows the [ASF release policy](https://www.apache.org/legal/release-policy.html). See for an archive of historical release notes along with JIRA issues relevant to each release. @@ -431,4 +431,4 @@ PLATFORM API Fineract does not provide a UI, but provides an API. Running Fineract locally, the Swagger documentation can be accessed under `https://localhost:8443/fineract-provider/swagger-ui/index.html`. A live version can be accessed via [this Sandbox](https://sandbox.mifos.community/fineract-provider/swagger-ui/index.html) (not hosted by us). -Apache Fineract supports client code generation using [Swagger Codegen](https://github.com/swagger-api/swagger-codegen) based on the [OpenAPI Specification](https://swagger.io/specification/). For more instructions on how to generate client code, check [this section](https://fineract.apache.org/docs/current/#_generate_api_client) of the Fineract documentation. [This video](https://www.youtube.com/watch?v=FlVd-0YAo6c) documents the use of the Swagger-UI. +Apache Fineract supports client code generation using [Swagger Codegen](https://github.com/swagger-api/swagger-codegen) based on the [OpenAPI Specification](https://swagger.io/specification/). For more instructions on how to generate client code, check [this section](https://fineract.apache.org/docs/develop/#_generate_api_client) of the Fineract documentation. [This video](https://www.youtube.com/watch?v=FlVd-0YAo6c) documents the use of the Swagger-UI. diff --git a/fineract-doc/src/docs/en/colophon.adoc b/fineract-doc/src/docs/en/colophon.adoc index a58c229b254..57160c8cd33 100644 --- a/fineract-doc/src/docs/en/colophon.adoc +++ b/fineract-doc/src/docs/en/colophon.adoc @@ -4,6 +4,12 @@ *Built on*: {docdate} +Note the version in the URL path: + +* Latest stable: https://fineract.apache.org/docs/stable/ +* Bleeding edge: https://fineract.apache.org/docs/develop/ +* Specific version: https://fineract.apache.org/docs/1.14.0/ + For document authors and changelog, view code history for the `fineract-doc` directory in https://github.com/apache/fineract/. toc::[]