[sword-devel] Project "Free Scriptures" started

Jaak Ristioja jaak at ristioja.ee
Wed Feb 26 02:04:08 MST 2014

Hash: SHA1

Hi, Jonathan!

On 25.02.2014 15:49, Jonathan Morgan wrote:
> I've been around CrossWire for quite a few years without actually 
> being part of the official group, so I think my opinion might be 
> helpful here as I don't have any turf to defend (CrossWire 
> regulars: please chip in if I'm misrepresenting anything).

Thank you for your response which I really appreciate.

> I think it's perfectly reasonable to criticise choices such as VCS 
> and the patch approval process. What is unreasonable is to expect 
> project maintainers to listen just because you have made that 
> criticism.  SWORD is a mature, feature-ful and complex library,
> and as result I'm fairly happy with a default attitude of "if it
> ain't broke, don't fix it".

I agree that it were unreasonable to expect maintainers to act without
thinking. I agree that SWORD is mature, featureful and complex. And I
agree with the attitude "if it ain't broke, don't fix it". However,
that exactly is the problem. SWORD is broken in different ways. Please
bear with me and let me demonstrate:

While SWORD does what it is supposed to do in 99% of its use cases,
this does not mean it is correct. One example of this kind of
brokenness was how it retrieved module information from web servers.
It basically parsed the directory index information HTML page returned
by the Apache server and failed if the directory index was not present
or contained a bit different HTML. The code parsing it also contained
flaws which led to invalid memory accesses. But it for 99,99% of the
time it was never triggered (at least nobody complained). This leads
us to a different type of brokenness.

The HTML parsing code was really a hack, simply searching for "<a
href=" strings from the HTML and trying to extract links to the files
of that directory. It still would not work if those links contained
non-alphanumeric characters, e.g. a forward slash (/). So it's really
fragile (fortunately Apache HTTPD has not changed it's default
directory listing format much). The parsing code doesn't really
correctly parse the HTML anyway, and is really a hack. It works
99,9999% of the time for us, maybe has never failed, but its a hack.
This isn't proper parsing. This leads us to yet another type of

Architectural brokenness. In this context and in long-term, it is a
fundamentally wrong choice to try to parse HTML generated by the web
server. I mean for a quick short-term
(we-just-want-it-to-work-fix-it-later) hack - sure, of course. But
this code has probably been there for ages. An architecturally better
solution would have been to put SWORD-specific index files on the web
server, which have strict semantics defined by SWORD and would be much
easier and safer to parse, and more reliable. In addition,
architectural brokenness often results in more complex code and APIs
which are not easy to understand (especially for new developers, which
I assume SWORD needs to attract) and not easy to fix. In my opinion,
such brokenness leads us to yet another type of brokenness.

The SWORD project doesn't encourage such changes to be made.
Architectural changes most often require huge changes in code. When
refactoring for this, one likely hits several new architectural flaws
which need to be fixed before the original can be fixed properly... A
kind of cascade or snowball effect. And if I were to submit a large
patch for this, it would probably get rejected. For me it would
probably take a week to fix this (and the cascaded things) in code,
but as a volunteer I simply do not have the several weeks or months
trying to convince the gatekeepers of the SVN. I agree that of most
likely the first patch ain't perfect, but messing with mailing these
patches and all of that just too much (compared to branching,
pull-requests and merging in DVCS). I'm sorry but I simply can't
afford the time and effort for all this process, I too have other
responsibilities in my life.

To sum up this comment: SWORD most likely has more (hidden) flaws
which result from poor (or outdated) architectural decisions, which
need big changes in code. IMHO the SWORD project is rather stagnant
and doesn't do much encourage such changes to be made nor make the
best decisions in favor of attracting new developers.

> I could be wrong, but my gut feel is that there are not many in the
> different front end teams that have actually made changes to SWORD,
> and I don't see that changes to VCS / patch approval process are
> likely to change that.

But I think it were a step in the right direction.

> While sharing code is good in theory, trying to make changes / 
> improvements which are acceptable to all frontends is a lot harder 
> than just making something which will work for your personal 
> frontend (I've tried).  As a result, unless we want to have a 
> different fork of SWORD for every frontend, with the resulting 
> chaos, changes to SWORD affect more people and so will be harder
> to get in (and should have a higher quality control / review 
> barrier).

How about we fork Sword into Sword 2 (NG) and Sword 1 (Legacy)? Lets
keep Sword 1 as stable as possible, and do a total makeover on Sword 2
as a software and as an open source development project? If such
efforts don't happen inside the Sword project, then these are more
likely to happen outside the Sword project (e.g. project "Free

> It's also unreasonable to connect these choices to the "freeness" 
> or otherwise of the software.  As with all GPL software, you have 
> the absolute freedom to modify it to your heart's content and to 
> host it on a different version control system (though you will
> have to identify how it is changed and possibly rename it).  If you
> want those changes to go back to the main repository, then people
> need to check that they work and that they don't break anything
> else.  I would say most large open source projects have a fairly
> careful review process, some more stringent than CrossWire's.
> There's nothing special about the way CrossWire has done it.
> Contributing code back to open source software is not a right -
> it's a privilege, and the privilege has to be earned.

Agreed. However, please consider in this context that not getting
Sword forked by outsiders is also becoming a privilege to be earned.

Blessings! :)
Version: GnuPG v2.0.22 (GNU/Linux)


More information about the sword-devel mailing list