[sword-devel] Contributing to sword-tools repo?

[Troy A. Griffitts]

For those who don't want to go back and read the threads Greg has
posted, and since I am the 'admin' mentioned for trunk of libsword, I'll
make a few brief comments which I hope summarized those emails.

I understand a move to git is likely inevitable.
____

I like SVN better and I know many people think I'm crazy for that.
Sorry, I do.  I find it takes me 3 arguments and 5 minutes to do the
simplest things with git.  Sorry, I am sure it is my deficiency and
inability to change my SVN-infected brain to "think in terms of git"--
which I have often been told.
____

Having said that, I have used git exclusive for SWORD development for
over a year, in an effort to become more comfortable with git.  The
git-svn bridge basically allows me to have a local git repo cloned from
the SWORD SVN repo, create branches and switch between those branches
and just do normal git things.  When I'm all done, a simple command:

git svn dcommit

will wrap up all my changes and commits and send them up to the SVN repo.

and a:

git svn rebase

will assures my local git repo is in sync with any changes others have
made out in the SVN repo.

If you really like git and really can't work with SVN, then I would
suggest the git-svn bridge.  It is really non-intrusive, once it's all
setup.  I'm happy to share my setup with you if you need help getting
started.
____

There is a large distinction which should not be overlooked between git
and github.  I don't believe switching to a crosswire-hosted git repo
will make much of a difference for collaboration (as just stated, I
already use git for SWORD development).  I appreciate the additional
services which really enhance collaboration provided from sites like
github, i.e., pull requests.
____

This is the part I'm sure will be much less appealing and likely
offensive to many of you.  I do believe that the SWORD engine is mostly
solid.  It has progressed over a period of 25 years and runs on a ton of
platforms and is really a fairly complicated and optimized chunk of
code.  libsword is similar to other libraries like zlib or ImageMagik or
graphiz; many projects rely on the library and changes should not be
made hastily-- they affect many projects and it takes a long history
with the code to know all the ramification of a change.  libsword is not
GREAT, but I do think it is really good and does a lot of stuff, from
syndicated module repositories and module installation management, to
parsing and referencing multiple versifications, to filtering
(transforming) from and to a number of markup formats, encodings,
encryption, features, attribute level entry map parsing and retrieval,
compression, supporting modular storage and  drivers, multiple search
engines, locales, and more.  In a complex system used by many projects,
it is not easy to contribute to a core library.  I review all submitted
changes and give advice for quite some time before giving rw trunk
access to a developer.  There are probably only 7 or 8 individuals with
full access to the entire repository.  Others have access to individual,
less critical parts of the tree.  People have complained over the years
that I don't accept code when submitted.  I refuse submissions for a
number of reasons.  Sometimes the code serves no purpose but to rewrite
working code in a more en vogue way.  Sometimes the code introduced a
3rd party dependency that, while it might make things a little easier,
also increases our reliance on a library we need to be sure continues to
work on all the OSs and architectures we support; I lean toward doing a
little more work if it avoids a 3rd party dependency.  Many people do
submit patches which are incorporated into the code base, but it is
usually after a few rejects with suggestions, and almost always with
lots of conversation back and forth before any change happens.  I know
this may seem to be against the free and open model of open source
development, but I don't think it is.  Changes to core components of a
project can be tightly managed while still giving entire freedom to see
and use the source code.  I believe strict management of the libsword
core has enabled it to survive and always progress (even if slowly) over
our 25+ years of development.

Huge parts of the engine are submissions by other individuals.  I don't
want to do all the work myself.  But I do want to assure that the
library continues to work for all the projects which use the library.  I
feel it is my primary task as a library administrator.  I am a firm
believer with Joel on Software that one should never rewrite a working
code base ( http://www.joelonsoftware.com/articles/fog0000000069.html )
but instead make baby steps forward.  I am very pragmatic.  You'll often
hear me ask the questions: why? what's the problem you're having that
you're trying to solve?  what can't you do with how things work right
now?  have you tried your patch with a working frontend and how has that
worked out?  Changing working code is always a heavy negative weight in
my mind and you'll need to justify the benefit of a change with a
heavier weight.  There are plenty of new features which need to be
written that provide real world, end user benefit, to make theoretical
changes because it is how project X does it or how University Y teaches
it, not a priority for me or worth the problems that come with any code
change.  I certainly want to provide new features to the users of our
library and thus on to their end users.  I do not want to rewrite
working code to rewrite code.

I believe this is the long-standing complaint that brings people to say
things like, the admins don't want contributions.  This is certainly not
true.  I don't want many contributions offered without respecting the
codebase which is already working and in place.  I don't want
contributions from individuals who aren't willing to spend the time
necessary to understand the complexity of the internals of the engine or
the very difficult problem we are trying to solve with the engine.  It
is actually a much more difficult problem than most people understand
until they get into the details.  I do welcome people who want to work
together, understand why things are the way they are right now, have a
real world feature they would like to implement, and then work together
to discuss the incorporation of that feature, test it out with frontends
in the field and then submit a collaboratively designed and well tested
patch.

Many projects at CrossWire do have loose to medium submission policies:
sword-tools, flashcards, swordweb, parts of libsword: filters, unit
tests, examples, make system, bindings, locales, et. al., new projects
are encouraged and near complete autonomy is granted to those projects
wishing to become part of the CrossWire community to be managed how the
project leaders see fit. But the core engine architecture, policies, and
code are not loose.

I hope that, even if you disagree with my tight management and
submission policy for core libsword, this might at least gives you some
understanding of why.

-Troy





On 01/14/2016 08:53 AM, Greg Hellings wrote:
> Matej,
> 
> Yes, I wasn't meaning to target you directly with my response. My
> comments were meant for newcomers to the thread.
> 
> --Greg
> 
> On Thu, Jan 14, 2016 at 9:24 AM, Matěj Cepl <mcepl at cepl.eu> wrote:
>> On 2016-01-14, 15:06 GMT, Greg Hellings wrote:
>>> Based on the way this conversation has gone in the past, nearly
>>> everyone involved except the project administrator would welcome a
>>> migration to git. Even if it was a self-hosted git. But the project
>>> admin remained unconvinced the last time the topic came up.
>>>
>>> So please, don't re-open this old sore spot. Sword is in SVN, hosted
>>> on the crosswire server, and there it shall remain.
>>
>> Just for clarification ... I was trying to englighten a newbie
>> about the situation.
>>
>> a) Maintainers of the Sword project have every right (legal or
>>    otherwise) to do whatever they want to do with their project
>>    in terms of VCS. If I don't like it, I can fork. The fact
>>    I haven’t means, I am not pissed of enough (and I am not C++
>>    programmer).
>> b) I don't expect a change to happen, so I focus my efforts on
>>    maintaining my own OSIS modules outside of the official
>>    Crosswire infrastrcuture and so far nobody made me any
>>    problems and my modules are occassionally even accepted
>>    (sometimes ... CzeNKB and CzeKMS modules were still not
>>    removed, but perhaps one day it happen as well; if not, I can
>>    survive).
>>
>> Best,
>>
>> Matěj
>>
>> --
>> https://matej.ceplovi.cz/blog/, Jabber: mcepl at ceplovi.cz
>> GPG Finger: 89EF 4BC6 288A BF43 1BAB  25C3 E09F EF25 D964 84AC
>>
>> If we rise from prayer better persons, our prayers have been
>> answered.
>>   -- a Jewish prayer book
>>
>>
>> _______________________________________________
>> sword-devel mailing list: sword-devel at crosswire.org
>> http://www.crosswire.org/mailman/listinfo/sword-devel
>> Instructions to unsubscribe/change your settings at above page
> 
> _______________________________________________
> sword-devel mailing list: sword-devel at crosswire.org
> http://www.crosswire.org/mailman/listinfo/sword-devel
> Instructions to unsubscribe/change your settings at above page
>