Skip to content

Comments

FINERACT-2336: improve asciidoc post-1.12.1 release#4914

Closed
meonkeys wants to merge 1 commit intodevelopfrom
release-doc-fixes-squashed
Closed

FINERACT-2336: improve asciidoc post-1.12.1 release#4914
meonkeys wants to merge 1 commit intodevelopfrom
release-doc-fixes-squashed

Conversation

@meonkeys
Copy link
Contributor

@meonkeys meonkeys commented Aug 1, 2025

Description

See FINERACT-2336 and detailed change descriptions in the commit log message.

Please have a look at the rendered HTML and PDF outputs, and compare them with https://fineract.apache.org/docs/current/.

Please pay special attention to changes in "Step 13: Close Release Branch"--there's an open discussion about how to do this properly. The steps work as indicated in this patch, but it eschews a flat commit trail in favor of simplicity while closing a release branch.

Checklist

Please make sure these boxes are checked before submitting your pull request - thanks!

  • Write the commit message as per https://github.com/apache/fineract/#pull-requests
  • Acknowledge that we will not review PRs that are not passing the build ("green") - it is your responsibility to get a proposed PR to pass the build, not primarily the project's maintainers.
  • Create/update unit or integration tests for verifying the changes made.
  • Follow coding conventions at 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
  • Submission is not a "code dump". (Large changes can be made "in repository" via a branch. Ask on the developer mailing list for guidance, if required.)

* 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:
    * asciidoctor/asciidoctorj-pdf#25
    * jruby/jruby#5573
    * asciidoctor/asciidoctorj-pdf#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 e090da2
* 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
@meonkeys
Copy link
Contributor Author

meonkeys commented Aug 1, 2025

Huh, that was an odd test failure:

  org.apache.fineract.integrationtests.datatable.DatatableIntegrationTest
  
    Test validateCreateReadDeleteDatatableWithCaseSensitive() PASSED
    Test validateInsertNullValues() PASSED
    Test validateCreateAndEditDatatable() PASSED
    Test validateCreateReadDeleteDatatable() PASSED
    Test validateReadDatatableMultirow() FAILED
  
    org.opentest4j.AssertionFailedError: expected: <1582-10-13 11:16:23> but was: <1582-10-23 11:16:23>
        at app//org.apache.fineract.integrationtests.datatable.DatatableIntegrationTest.validateReadDatatableMultirow(DatatableIntegrationTest.java:810)

I'll see if I can repro that locally.

I'm also going to close this and create a new PR merging from my fork instead of from a branch in this repo (to prevent duplicate jobs in github actions CI).

@meonkeys meonkeys closed this Aug 1, 2025
@meonkeys meonkeys deleted the release-doc-fixes-squashed branch August 1, 2025 19:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant