similar to 45404bafba
All asciidoctor config must be in `fineract-doc/src/docs/en/config.adoc`.
In this case `:sectnums:` re-starts ToC section numbering partway through the ToC.
I started editing this just to fix the link to the "Pull Requests" doc (it moved from README.md to CONTRIBUTING.md), but then I saw a few other places in need of service.
* use Markdown links for readability
* add link to pull request size limit wiki page re: code dumps
* remove link to PR 1284, it doesn't add anything here and takes the reader out of context
* add link to mailing list
* add link to testing docs
* release step 6: emphasize "re-run the command above"
* release step 9: link to Database Setup in e2e or integration section (currently links to e2e since `cucumber.adoc` precedes `integration.adoc` in `fineract-doc/src/docs/en/chapters/testing/index.adoc`)
* release step 10: improve rc verify instructions in voting email, based on https://lists.apache.org/thread/jk2qzjxc89hd1c8xzvhtmlbbj1m8ktbl - thread: "release process improvement (was: 🗳️ 1.13.0 for release)"
* release step 15: use current mission statement from top-level readme in release announcement email
* release/1.13.0:
don't include actual email addresses
save 1.13.0 vote result
shorten/simplify gpg key sending commands
update link to rc verification instructions
fix typos in step 9 re: running the binary
improve step 9 artifact verification gpg tips
fix tarball explosion in release step 9 🧯
cucumber.adoc: fix list continuations
further improve release steps 6 and 9
release step 6: fix sanity check example
improve staging doc and commands in release step 8
doc: remove errant config but keep :sectlinks:
clean during artifact build release step 6
FINERACT-2326: Do not remove external id if transaction got not replayed
FINERACT-2326: Fix `Trial Balance Summary with asset owner` report
FINERACT-2326: Loan point in time API now properly handles future dates
improve release branch email template
improve release process kickoff email template
Originally I thought I was causing issues by running `./gradlew clean` separate from `./gradlew srcDistTar binaryDistTar`. If I did (or so I thought), a `fineract-provider/build/classes/java/main/git.properties` file was _sometimes_ not generated (the `generateGitProperties` task failing, misbehaving, or not even running? was the file getting deleted? no idea).
Unsure of the cause, at least I understand that file is supposed to end up at `BOOT-INF/classes/git.properties` in `fineract-provider-VERSION.jar` in the binary release tarball. Its contents are displayed at the `/fineract-provider/actuator/info` endpoint. I think that's more or less how it works, but I did not spend enough time on this to be certain.
Now I think it wasn't at all related to how I was running our Gradle tasks, but rather some nasty behavior in gradle-git-properties:
* https://github.com/n0mer/gradle-git-properties/issues/233
* https://github.com/gradle/gradle/issues/34177
Yuck. 🤢
See 89e9cfcd7d
I think this was a typo. It's presumably changing the highlighter midstream and causing section numbering to start at the "Fineract Development Environment" chapter. But I really like `:sectlinks:` and I want to keep that! It's handy for sharing deep / sorta permanent links to specific sections (just click on any heading and copy the URL).
I think the `clean` task is important here, Felix and I were seeing
issues with jar filenames with incorrect version numbers. His work on
FINERACT-2341 may have fixed whatever was causing it, but let's
also/still do the `clean` before building release artifacts / candidates
just to be safe.
* update release notice years in NOTICE_RELEASE and NOTICE_SOURCE
* step 5
* simplify mention of tests: "Ensure all tests pass for this commit both in CI and locally"
* recommend GPG signing annotated release tag
* step 8: improve svn commands
* This way is simpler and more efficient, especially with a bunch of release candidate dirs in the staging area.
* step 10: mention need to test rc before +1 vote -- See:
* https://www.apache.org/legal/release-policy.html#release-approval
* https://www.apache.org/legal/release-policy.html#approving-a-release
* step 12: only PMC members can upload releases
* step 13: simplify & explain "finalize branch" instructions
* Document what worked for me for 1.12.1.
* I didn't need to create the extra `merge-$VERSION` branch and do the recursive merge.
* document how asciidoctor upgrade is blocked
* see "official docs - deps stuck" thread on fineract dev mailing list
* https://lists.apache.org/thread/7mmsj13spb11vgz0z38fhwgzwtq03brr
* can't upgrade to 4.x because of one of these:
* https://github.com/asciidoctor/asciidoctorj-pdf/issues/25
* https://github.com/jruby/jruby/issues/5573
* https://github.com/asciidoctor/asciidoctorj-pdf/issues/16
* improve asciidoc config - opt for simplicity where the complexity adds nothing
* compat-mode is off by default, no need for it here
* default optimization should be fine
* media should have been screen | print | prepress, just leave it as default instead
* page size? I really don't think this is going to be printed much, just go with default
* PDF version 1.8 is invalid, just use the default unless we someday have a good reason to pin this
* reduce copyright years sources of truth
* see also: https://docs.asciidoctor.org/pdf-converter/latest/asciidoc-attributes/
* remove unnecessary asciidoctorj 3.0.0 version string -- no need to pin this
* remove prompt character from Bash shell examples
* it isn't properly syntax-highlighted and it looks confusing with line numbers (which we might want to add)
* it isn't necessary
* the prompt character ("%" in this case) is not typically included in shell code examples because it makes it harder to copy and paste shell code examples
* $ is likely more common than % (at least on Debian/Ubuntu), but either way I'd say exclude it
* fix source code syntax labels - use "bash" only when it is actually Bash shell code
* persistence.adoc
* fix broken enumerated list
* resolves these warnings seen with, e.g.: `gradle --info doc`
* `Jul 27, 2025 8:26:48 PM uri:classloader:/gems/asciidoctor-2.0.10/lib/asciidoctor/parser.rb parse_list_item`
* `WARNING: chapters/architecture/persistence.adoc: line 104: list item index: expected 1, got 2`
* `Jul 27, 2025 8:26:48 PM uri:classloader:/gems/asciidoctor-2.0.10/lib/asciidoctor/parser.rb parse_list`
* `WARNING: chapters/architecture/persistence.adoc: line 110: list item index: expected 1, got 3`
* fix wrapping (we use hardbreaks)
* fix typo: `s/plane text/plain text/`
* switch to rouge syntax highlighter - it handles more source languages
* fix broken long shell code lines
* fix .avro file syntax highlighting (it's JSON)
* configuration-gpg.adoc
* fix accidental block continuation
* One little plus sign was making `= Email` appear verbatim in rendered output because it was interpreted as a list continuation.
* See https://docs.asciidoctor.org/asciidoc/latest/lists/continuation/#list-continuation
* recommend more secure keys
* add a line continuation for an enumerated list
* architecture-overview.puml: remove this unused (likely a "Hello World") diagram
* release-schedule.puml: fix pluralization of days
* purely aesthetic: doesn't affect chart rendering
* fix src/bin/binary tarball name typos
* missed a few in e090da2a01
* fix release branch name
* must match `release/{revnumber}`, per gitVersioning stanza in top level build.gradle
* harden.adoc: fix broken link to CISA
* fineract-doc/build.gradle
* ensure HTML task has diagrams and images availble
This quality of life patch reduces static weaving log message priority,
reducing the default gradle build output by about 60 lines.
example gradle run with these messages:
> Configure project :custom
ℹ Skipping static weaving configuration for non-Java project: custom
> Configure project :fineract-accounting
Configuring EclipseLink static weaving for fineract-accounting
> Configure project :fineract-branch
Configuring EclipseLink static weaving for fineract-branch
...
Release tarballs are currently renamed (without changing the contents): apache-fineract-src-1.12.1.tar.gz becomes apache-fineract-1.12.1-src.tar.gz . The former matches the exploded directory name, the latter does not. The difference is subtle but meaningful... I strongly prefer the former because it's less surprising / more common, and easier to work with from scripts.
There's no functional difference, this should only impact aesthetics.
I did also shorten `binary` to `bin` so release artifact name lengths match.
* fix various typos, spacing, formatting issues
* fix links to legacy docs in API docs
* update keycloak oauth dev instructions
* update default oauth URL for latest Keycloak
* use consistent quoting in oauth docs (single quotes)
* use asciidoc auto-enumerated lists whenever possible
* migrate security topics from readme into asciidoc: oauth, 2FA, HTTPS
* move :hardbreaks: setting to config file so all config settings are in one place. (I think it's fine that `license.adoc` will use hardbreaks -- that's how the plain text version is formatted so it should look more familiar)
* add intro to security chapter
* migrate in Securing Fineract wiki content from https://cwiki.apache.org/confluence/display/FINERACT/Securing+Fineract
* just say "oauth" (not "oauth2") to conform terminology throughout docs -- OAuth 2.0 is just the latest version
* cross-ref HTTPS section from Securing Fineract
* reposition hardening options as tips
* see also: https://lists.apache.org/thread/81qdxttffp6wn23c48zvk93hc13373qv
* simplify/clarify example oauth curl requests
* Testing just now and I didn't need --location.
* Also I imagine folks will need --insecure with the self-signed default cert in dev.
* don't change default oauth URL
* no surprises for existing deployments
* clarifies the keycloak v26 example
* docs: link directly to FINERACT-873 and shorten it for brevity / clarity
* fineract plugin:
* print email, don't send (WIP, but I might keep this... I prefer manually sending emails for now.)
* support different release date and release branch date
I originally modified EmailService (disabling the actual email sending by just commenting it out) but I reverted that change per discussion with Ádám Sághy. You won't see this in the squashed final commit so I'm mentioning it here for posterity.
Ádám wrote:
> Is there a reason to remove the email sending?
I replied:
> Great question. I did think about this for a bit. I should have been more transparent about my intent. Allow me to explain.
>
> For the 1.12.0 release process I used the groovy code to generate email templates, but I wanted to edit the emails before sending so I disabled this line, and intentionally left it so, figuring I'd be the one using and [hopefully minimally] maintaining it for now.
>
> The Fineract (release) plugin appears to be more or less unmaintained for about 2 1/2 years now (save the semiautomated dependency updates). Looking at the code and history, I assumed I was the only one that would be using it now and in the near future. It also struck me how most everything it does is primarily to work around antiquated Apache release process steps that are not necessarily what we want for Fineract. Personally I think the Fineract release plugin should be simply replaced by a better release process.
>
> I think I'll add a comment there, and of course I welcome your feedback.
>
> Anyway yeah, my intent here was simply to do the simplest, safest, and most useful change here so I could keep this release plugin limping along until we improve the release process itself. No disrespect to @vidakovic and @vorburger and whomever else poured love into this code over the years. Perhaps the options for releasing Apache code have improved since then?
>
> Today we can of course do better (e.g. just let GitHub help us release with far fewer clicks/steps).
>
> Also I am not proposing we change the release process today or even soon. Maybe in a quarter or two I'll propose changes, if/when there seems to be political will around that.
Ádám replied:
> hmm... i am not particularly mind if you are reworking the release process, but i think having a "send" step which was meant to sending a mail but now the actual sending got commented out is misleading, no?
I replied:
> Yep, you're right. I think I'll just back out this change because I agree with you it's bad to just leave the send() call commented out without any other changes.
* don't bother making MD5 files, they aren't necessary
* step12 changed, stub it out and reference FINERACT-1817 for future improvements (looks like svn mv is not yet supported)
* use latest vote message template, based on https://lists.apache.org/thread/cs5t0ho39ktg2jxr74dqd7fg9nyfcz3k
* use more explicit form of `git push` to push release tag, see https://stackoverflow.com/questions/5195859/how-do-you-push-a-tag-to-a-remote-repository-using-git
* use consistent language re: tarball, file, artifact, release candidate
* fix some source listings that shouldn't be using macro expansion: this messes up URLs (hides scheme)
* fix asciidoc link to FINERACT-1229
* clean up copyright years: use variable properly and remove unnecessary extra copyright in preface (it appears directly above, in the license)
* de-indent URL in apache license -- this makes the link clickable in rendered HTML and PDF asciidoc outputs
* disable broken fineract-client API asciidoc include
* this has a side effect of removing ~1,200 pages from the PDF
* remove duplicated/outdated text, reduce sources of truth
* link to current FAQ
* introduction is all references now... it was way out of date and also needed formatting fixes
* unset `show-link-uri` to improve PDF rendering
* remove unnecessary/unused `.asciidoctorconfig` file
At some point, Liquibase added an analytics/telemetry "phone home" to gather user data.
I get how companies and FOSS projects greatly benefit from knowing more about their users, but I think this should only be done with proper consent. I would not assume/expect any libraries to send analytics home. The default behavior of trackers like these should always be to *not* phone home without a user first consenting / opting in.
---
I'm not sure this is the right change, but it works (feedback welcome). My naïve test/check to know this works is visually inspecting the output of the log message I added in TenantDatabaseUpgradeService to see if `liquibase.analytics.enabled` is set, and to what. I'm happy to automate this, but it seemed unnecessary (again, feedback welcome).
We could also disable the phone home with an environment variable ( LIQUIBASE_ANALYTICS_ENABLED=false , see https://docs.liquibase.com/analytics/home.html ). I'm not sure where that should be set if we did. Likely several places (for build/dev/test/ci/qa/etc.).
I originally noticed the phone home because I block requests from my computer to 3rd party tracking/analytics services, and I was getting this error in my console:
java.net.ConnectException: Connection refused at liquibase.analytics.LiquibaseAnalyticsListener
At first I misunderstood this as a database connection error, but it was really just liquibase throwing an error because it couldn't connect to its own analytics server.
If we were to create a configurable property, I think the ideal place to set the value would be in fineract-provider/src/main/resources/application.properties, (default to false, allow override) but our version of spring boot doesn't support it yet ( see https://github.com/spring-projects/spring-boot/issues/43067 ) so we'd have to add the usual scaffolding required for a Fineract setting. I'm not sure we want/need that, because I can't imagine anyone *wanting* to set the flag to `true`, and my naïve hardcoded global change is less code to maintain than providing a configurable setting. If there's demand to make it configurable later, we could of course do that (especially once it becomes easier to do so). I feel like how we let Liquibase behave is up to us, though. An under the hood / upstream decision we get to make.
See also:
* https://lists.apache.org/thread/5s7zjsxdcqk1qvjnc1wbhqqv66shpl54
* Analytics is enabled by default in OSS version · Issue #6503 · liquibase/liquibase · GitHub https://github.com/liquibase/liquibase/issues/6503
* Add a method for Spring Boot to configure the new analytics feature · Issue #6501 · liquibase/liquibase · GitHub https://github.com/liquibase/liquibase/issues/6501
I noticed an extra `v1/` while visiting https://localhost:8443/fineract-provider/swagger-ui/index.html
All fineract-provider (unit) tests passed.
I also manually tested out hitting a few /api/v1/ endpoints via the Swagger UI web page at the URL above and those worked as well.
Adam Monsen