Changes http://wiki.axiom-developer.org/HowToSubmitPatches/diff
--
This page describes how to submit a piece of code that corrects or
extends the Axiom project.
In general a patch file is of the form::
cd the.dir
diff -Naur file.pamphlet file.pamphlet.new >the.dir.file.pamphlet.patch
Send the patch to <a href="mailto:[EMAIL PROTECTED]">Tim Daly</a>.
This has several
features:
* it tells where the patch is being applied
* the Naur options gives context
* the impact of a change to multiple files become visible
Tim Daly reads the patches before applying them, so be sure to document the
reasons for the change in the pamphlet file. It may seem trivial
but remember that I didn't do the initial analysis so he, and others,
will have to understand after the fact.
In most cases in a pamphlet file if you're changing a few lines
of code or a whole function it should be documented thus::
...
(defun foo ()
(list
"this is ok code"
"this is broken code"
"this is also broken"
"this is ok"
)
)
turns
into::
\subsection{foo list fix}
This code used to read:
\begin{verbatim}
"this is broken code"
"this is also broken"
\end{verbatim}
but clearly the elements of the list are wrong. We are going to
print this list for the user so we don't want them to know anything
is broken. Thus we have wonderful new code that will inspire confidence.
This list is printed with the [[printlist]] function.
<<foo list fix>>=
"this is great code"
"this inspires confidence"
@
...
(defun foo ()
(list
"this is ok code"
<<foo list fix>>
"this is ok"
)
)
and, yes, that this is tedious.
In general, it is also useful to update the pamphlet files with
documentation-only changes as you understand what a block of code
is intended to do. Most of this information has been lost to history
and the world can leverage your efforts at understanding if you take
the time to document it. In many ways this is as important as fixing
the code.
**PS**: We will soon have another way to submit patches, since any modification
should
first go into the <a href="../AxiomDownload">silver branch</a> and survive
public review,
but the need to document properly will not be modified.
--
forwarded from http://wiki.axiom-developer.org/[EMAIL PROTECTED]
