Lots of changes, reviewed by several, lots of discussion already, so I'm going to push commit on this shortly. With thanks to Felix.
On Sun, Oct 12, 2025 at 3:53 AM Felix van Hove <[email protected]> wrote: > Hello James, hello everyone, > > Latest changes here: > > https://github.com/apache/fineract/pull/5076/commits > > After you click on the commit link, please make use of the "View File" > option reachable from the three dots to inspect both CONTRIBUTING and > README. > > I have removed the tagline on top of the README and added "thank you, > Mifos, for supporting the Slack channel" to the Slack channel reference. > > There is still a link pointing to a Mifos Sandbox at the very end of the > latest README proposal, along with this remark: "(not hosted by us)". > Not sure, if you or anyone wants me to replace this by "(thank you, > Mifos, for hosting this)". > > I prefer not to continue the discussion on how much roadmap and the PMC > have been shaped by vendors in the past months. But I'm clueless what to > do with the original section referencing API clients and demo Sandboxes > - and have therefore not re-inserted it. To me it sounds highly > artificial (and actually misrepresenting reality) to list these (in > avoidance of "Mifos") under a title "Other related open source projects" > - and I can't believe this opinion is not shared by others, even you, > James. Anyone who wants to bring the section back, please provide the > concrete text. > > Finally, given the current (much reduced) length - shall I re-establish > the TOC? I wasn't sure what your, James, ultimate opinion is now, > neither what the general opinion is. > > > > On 12/10/2025 00:30, James Dailey wrote: > > Felix +1 and thank you. > > > > Note my comments below to respond to you. > > > > On Fri, Oct 10, 2025 at 12:53 PM Felix van Hove <[email protected] > > > > wrote: > > > >> Hello everyone, > >> > >> I've updated the README PR draft and changed the following points of the > >> initial version: > >> > >> 1. I've replaced the mission statement, i.e. the very first part of the > >> README. I took the text from Javier Borkenztain's email, because it > >> seemed to have most votes in favor of it. Note that the title on top of > >> everything is still the same ("Apache Fineract: A Platform for > >> Microfinance"). I made a suggestion for its replacement, but there was > >> no discussion, as far as I can see. > >> > > > > I think we should just drop the tag line "a platform for microfinance" as > > our mission statement is now broader. > > We could replace it with "core banking and lending" but I think we don't > > need a tagline in the readme. > > But, we can make that change later too. > > > > > >> > >> 2. James Dailey, you asked for "not referencing Mifos in the Readme", > >> and Paul agreed. I have therefore removed all references to Mifos. I > >> don't think that makes sense and firmly believe it is unhelpful to > >> visitors (and Fineract shoots itself in the foot). I dropped the section > >> on API clients and demos, because I didn't see how this could possibly > >> be rephrased without mentioning the "Mifos" word. (Why, James, are top > >> representatives of vendors in the PMC okay, a roadmap (to a considerable > >> extent) shaped by vendor requirements is okay - but saying Mifos in the > >> README is not? We all have to recognize technical dependencies in > >> software. We should recognize all of afore as non-technical, practical > >> dependencies - we might like it or not.) If anyone disagrees with the > >> removal of the section, please make a concrete proposal - I'm more than > >> happy to bring it back. > >> > > > > *VENDORS ARE NOT REPRESENTED AT THE PMC* > > We all put on our Apache Fineract(R) hat when making decisions for the > > benefit of the project. > > Vendors (corporate entities) are never participants in the project, only > > individuals. > > Those individuals may be paid by a company to work on the project, but > they > > should always have the "benefit of the project" in the forefront. > > This is the pattern across all Apache projects. Unlike other open source > > foundations, the intent is to not have a "pay to play" model. > > > > *ROADMAP is DRIVEN BY NEEDS * > > You will note in my discussion with the Community that the Roadmap items > > are driven by user requirements > > and roadmap items get built by devs who are paid or unpaid (contributors) > > so, yes, there is a need to build consensus about what needs to be built > > with the widest possible group > > but also, if no one is doing the work (paid or not), then it's not a > > realistic roadmap > > We can only build what is both needed and contributed. > > > > Please read: > > https://community.apache.org/projectIndependence.html > > > >> "A primary purpose of the basic requirements the ASF places on its > >> projects is to help ensure long-lived and stable projects by having a > >> broad-enough community to maintain the project even in the absence of > any > >> individual volunteer or any sea change at a major vendor in that area. > The > >> Apache project governance model > >> <https://www.apache.org/foundation/governance/> is explicitly based on > a > >> diverse community. This is different from other governance models, like > the > >> “benevolent dictator” idea or the corporate-backed model that projects > like > >> Eclipse use. > >> Please Note: These requirements apply to *Apache projects*: that is, to > >> individual committer and PMC member behaviors and actions within the > >> context of collaboratively building software products *at The Apache > >> Software Foundation*. By definition, “Apache project” is the > >> collaborative activity of building and releasing software products at > the > >> ASF." > > > > > > *MIFOS in the Readme * > > What I was trying to express is that, looking around, there are no other > > Apache projects that I have found where a key vendor is mentioned in the > > README as a required part of the setup. I have been looking more, and > > sometimes vendors are mentioned for sponsoring something (test data?), or > > helping with a test instance, or something, so we could do that. But, we > > need fineract to "stand on its own" without mifos... which is the > > requirement. > > > > My suggestion to you, not a requirement to you, was to find a way to > > provide links to "Other related open source projects" which I see as a > bit > > of a compromise, as Mifos is both a vendor (in the ASF view) but also a > > kind of "custodial open source non-profit" with other, but highly > related, > > projects. As long as there is a clear separation between "what is > > Fineract" and "what is mifos", I think it's ok. But I may want others at > > the ASF to weigh in on this. > > > > I appreciate you trying to keep things clear and I think this level of > > clarity about role separation is important. > > > > So, if I understand the ASF "rules" correctly, we could "Thank Mifos for > > supporting the Slack channel" with a link, but without formally saying > > "this is our Fineract project slack". It does make a difference because > in > > the future, we may also thank abc, xyz vendors for supplying a different > > slack, discord channel, test data, hackathon, etc. > > > > > >> 3. I've removed the TOC, because Adam Monsen suggested so, although I > >> disagree again. More than anything else, a TOC gave future editors an > >> idea of where content is to be inserted (and some prior editors clearly > >> had not paid much attention); it gave the reader an idea of where to > >> look and what to expect; the times when a TOC required maintenance are > >> over: any change of the README is hopefully proofread by AI - in the > >> wake of which the TOC is updated automatically. > >> > > > > I guess I think that a README should never be long enough to need a Table > > of Contents. But, if it needs a TOC, then why not have it? > > > > > > > >> > >> 4. In the first version, I had assembled a chapter on "GUIDELINES FOR > >> CONTRIBUTING CODE", based on existing sections. I have moved all of this > >> and much, much more to CONTRIBUTING, because Adam Monsen and I are in > >> favour of it, and no one seemed against it. Please read the text of > >> CONTRIBUTING, because I added, rephrased and restructured content. > >> > > > > Do you mean this link ? > > https://github.com/apache/fineract/blob/develop/CONTRIBUTING.md > > > > > >> Initially I thought of moving significant parts of the "Instructions" to > >> the one-page platform documentation. (In this context, Adam Saghy and I > >> considered removing the section on Minikube altogether.) But I now think > >> we should get a first README version merged. So many changes already! > >> The platform documentation would profit from its own overhaul. We can > >> still hone small aspects of the README later. Let's get a new baseline > >> for the README! I have retracted the draft status. > >> > > > > Yes, fully agree. update readme as best we can for now. +1 > > But also recognize that you are helping to define the mission, vision, > > community with each clarification and so it is bound to create some > > discussion. > > keep moving forward. > > > > Minor, thing...I noticed a link in the top nav of the Readme to a > > Deprecated page that needs some work to bring up to date. > > https://cwiki.apache.org/confluence/display/FINERACT/Fineract+101 > > <https://cwiki.apache.org/confluence/display/FINERACT/Fineract+101> > > > > I think it should exist in the asciidocs or be maintained in the wiki. > > Which do you think? > > > > Felix > >> > >> > >> > >> On 10/10/2025 03:15, Paul wrote: > >>> 👍 > >>> > >>> On Thu, Oct 9, 2025 at 6:39 PM James Dailey <[email protected]> > wrote: > >>> > >>>> To repeat what I wrote in the github comments... > >>>> > >>>> +1 > >>>> This is great progress. I would however like to be even more explicit > >>>> about not referencing Mifos in the Readme. To reference a Vendor in > the > >>>> README is highly irregular in any other apache project. > >>>> > >>>> I think it might be appropriate to have other open source projects > >> listed > >>>> somewhere... i.e. "the following projects have committed to work on or > >> with > >>>> Fineract - external site referenced here warning links take you away > >> from > >>>> Apache.org... ... then with some links to those GitHub repos. But > >>>> describing a packaging approach with Mifos (as a vendor) is not > >>>> appropriate. > >>>> > >>>> It would be more appropriate to have a listing of all known vendors of > >>>> Fineract on the website, not the README. > >>>> > >>>> It fundamentally is against the Vendor neutrality obligation of the > >>>> project. > >>>> > >>>> > >>>> > >>>> On Thu, Oct 9, 2025 at 2:25 PM Adam Monsen <[email protected]> wrote: > >>>> > >>>>> On Fri, Oct 3, 2025 at 6:39 AM Felix van Hove > <[email protected] > >>> > >>>>> wrote: > >>>>> > >>>>>> https://github.com/apache/fineract/pull/5076 > >>>>>> > >>>>> > >>>>> TL;DR - Great work so far! > >>>>> > >>>>> 2. I suggest to move some parts of the current README somewhere else. > >>>>>> > >>>>> > >>>>> Yes! 100% agree. I'd love to get the readme down to "one page" > >> (whatever > >>>>> that means--let's just say *very* succinct). The rest can live in > >>>>> official docs or wiki. ~50% of the existing readme content should be > >> moved > >>>>> to the official docs and ~50% to the wiki. > >>>>> > >>>>> ( By "official docs" I mean the asciidoc sources in fineract-doc > >>>>> < > >> > https://github.com/apache/fineract/tree/develop/fineract-doc/src/docs/en>. > >>>>> ) > >>>>> > >>>>> I attached my suggestion. You can view it rendered here > >>>>> <https://codeberg.org/meonkeys/fineract-brief-readme> or here > >>>>> <https://git.disroot.org/meonkeys/fineract-brief-readme> (wait for > it > >> -- > >>>>> sometimes it takes a few seconds for the charts to render). Of course > >> if > >>>>> you accept this it's still only a third of the work, the rest of the > >> work > >>>>> is updating official docs, wiki, and a couple other markdown files > (see > >>>>> below). > >>>>> > >>>>> > >>>>>> - First of all, have you had a look at the CONTRIBUTING document? > >>>>>> Contrary to the README, it's too short. Is it okay, if I move what > is > >> now > >>>>>> "Guidelines for Contributing Code" over? > >>>>>> > >>>>> > >>>>> Sure, or to the official docs. And CONTRIBUTING.md should be updated > >> and > >>>>> kept short. > >>>>> > >>>>> > >>>>>> - Secondly, could we not move half of what is under "Instructions" > now > >>>>>> to the documentation page ( > https://fineract.apache.org/docs/current/) > >>>>> > >>>>> > >>>>> Yes, please do. > >>>>> > >>>>> > >>>>>> 3. I would like to add a section "Troubleshooting", but need your > >> input > >>>>>> for it. > >>>>>> > >>>>> > >>>>> This can go in the official docs too, once we have content for it. > >>>>> > >>>>> > >>>>>> 4. The current text remains extraordinarily long for a README, even > if > >>>>>> we move some sections somewhere else. To mitigate its complexity I > >> have > >>>>>> added a hopefully better structure to it (moved sections etc.) and a > >> Table > >>>>>> of contents. Okay? > >>>>> > >>>>> > >>>>> I don't want to add nor maintain a TOC. Let's just make the readme so > >>>>> short we don't need one. (side note: many tools generate a TOC for > you > >> by > >>>>> scanning Markdown headings, e.g. Vim Markdown > >>>>> <https://github.com/preservim/vim-markdown> and Markdown Viewer > >>>>> < > >> https://addons.mozilla.org/en-US/firefox/addon/markdown-viewer-webext/> > >>>>> ). > >>>>> > >>>>> 5. I've removed and/or merged a few sections. > >>>>>> > >>>>> > >>>>> 👍 > >>>>> > >>>>> 6. I'm not happy with the current DATABASE section and its position, > >>>>>> suggestions welcome. > >>>>> > >>>>> > >>>>> Move to wiki or official docs or axe it. > >>>>> > >>>>> Final thought: content in STATIC_WEAVING.md should be moved to > official > >>>>> docs or wiki. > >>>>> > >>>> > >>> > >> > >> > > > >
