[Texmacs-dev] Some guidelines for patches and contributions to the source code

[Joris van der Hoeven]

This mail is mainly meant for David, but it may become interesting
for others too. David just sent me a complex patch of 10.000 lines.
I cannot handle such patches in an efficient way.

I am glad to include all kinds of minor and major contributions into TeXmacs.
This takes a lot of time and I partly see this work as a service which
I give to other contributors, since it valorizes their work. Not all
patches are really fundamental, but you will not often hear me critize
someone in particular.

The service which I provide in this way has a counterpart:
contributions should be reasonably well structured and documented,
so that I can process them in a reasonable amount of time.
Let me tell you briefly how I proceed.

As soon as a new patch arrives, I do *not* test it.
In fact, I hardly *ever* test it. I rather look at the differences
with the existing code and analyze which parts of the patch
are good and which ones not. Once I have determined the good
parts, I copy them into the main source and maybe modify them.
This is done in a progressive way, while testing the additions.

This way of proceeding has many advantages for me. E.g.:
  * I know exactly what has been modified or added.
  * I have checked whether the new code does not cause major problems.
  * Changes are made directly in the newest version.

However, the contributors also have to make sure that
this working strategy can be carried out efficiently. This means:
  * The patch should have a well-identified scope:
    don't agglomerate independent patches together.
  * The patch should not be longer than needed.
    If it can be decomposed in several stages,
    then this should be done.
  * The patch should avoid the modification of too many files:
    it is very hard to precisely understand what has changed
    in such cases.
  * New added features in separate files are processed
    quicklier than modifications in existing code.
  * Please do not change names (or basic functionality) of
    existing functions all over the place if this is not essential.
    If you want to change the names of a set of functions,
    please note your proposals on a list and I will take care of it myself.

Thanks for your attention,


-----------------------------------------------------------
Joris van der Hoeven <address@hidden>
http://www.texmacs.org: GNU TeXmacs scientific text editor
http://www.math.u-psud.fr/~vdhoeven: personal homepage
-----------------------------------------------------------