Under-appreciated aspects of literate programming

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
7 messages Options
Reply | Threaded
Open this post in threaded view
|

Under-appreciated aspects of literate programming

Tim Daly
The bug list brings out several aspects of literate programming
that are not obvious at first glance but make a qualitative
difference in maintaining code. Previously people have turned
to IDEs to provide these features. IDEs are just more code to
maintain, often with very task-specific hacks that are, sigh,
undocumented. IDEs also require more learning to be effective.

In particular, if we contrast bug tracking using an online bug
tracker like github/savannah/sourceforge and a literate form
we can see some differences.

1) Organizing bugs in book form makes it easier to search.

No search tool is needed. We know how to search books,
by chapter/section titles or by index or by provided tables.
Search tools can be used if necessary because the latex
sources are just ascii text and some tools can search PDFs.

2) The ability to intertwine words with the bugs

Here we have the full power of latex rather than restrictions
like "no html". If the issue is mathematics we can include
equations. If the issue is html we can use verbatim. We
can use hyperlinks to external sources (just like bug trackers).
We can also include images for things like graphics bugs.

3) Bugs can be organized

Traditional bug trackers tend to use a stack architecture so
that the latest bugs appear on top. Time is not necessarily
the most useful organization.

They do have a useful feature of capturing discussions from
emails but this could be achieved using patch on the literate
document. They also track severity which is useful. This
could be achieved with simple color-coding in the literate doc.

4) The ability to extract literate chunks

Since sources are maintained in literate documents it is trivial
to extract bugs from a literate document. These can be pulled
into test files at build time and checked for changes. So a
change that fixes multiple bugs can all be highlighted at once.
Axiom uses a character-compare mechanism so any behavior
change will be obvious. Thus bug review is part of the build
process.

5) Bugs can be cited and hyperlinked

Bugs can be cited in the source code so a known issue can
refer to the particular bug. Hyperlinking between documents
means that it is possible to link from code-to-bug or
bug-to-code in the actual sources.

6) Bugs are part of the source tree

Promoting bugs to book form also means that they get regular
review. They are not "someplace else", such as a bug tracker
on a website. Submitting a bug report is the same process as
submitting a patch. So bug review is part of the release process.

7) Bugs are part of every program

Bugs are just another aspect of programming, like testing,
build systems, and documentation. It makes sense to treat them
as first-class source control objects. Having a "bug book" makes
it obvious where to look for bug reports.

Some points in the diatribe are bug-specific. But literate
programming in a pervasive form really does enhance the many
ways that code can be organized, maintained, tested, searched,
explained, and understood.




_______________________________________________
Axiom-developer mailing list
[hidden email]
https://lists.nongnu.org/mailman/listinfo/axiom-developer
Reply | Threaded
Open this post in threaded view
|

Re: Under-appreciated aspects of literate programming

Ralf Hemmecke-4
> 6) Bugs are part of the source tree

To me, it would be sufficient, if fixed bug come with a commit message
that describes the bug that is fixed and the source code contains a test
that corresponds to the bug.

I don't necessarily need open bugs in the source tree. They could live
in the same repository (note that git allows non-connected DAGs
(directed acyclic graphs) of commits in one repository), but I wouldn't
want open bugs hanging in the source repo.

Ralf

_______________________________________________
Axiom-developer mailing list
[hidden email]
https://lists.nongnu.org/mailman/listinfo/axiom-developer
Reply | Threaded
Open this post in threaded view
|

Re: Under-appreciated aspects of literate programming

Tim Daly
Fixed bugs seem uninteresting. Several things failed on my
car, for instance, that were fixed. There is rarely the need
to revisit failures, except possibly in regression tests, like
brakes :-)

Except for release notes, why would anyone want to know about
fixed bugs? At most someone running an old version might
want to know.

On the other hand, a known bug is an intrinsic part of the
system (mis-)behavior and is something worth noting. Why
would you want to keep that in, say github? Axiom has a git
repo at savannah, sourceforge, and axiom-developer. Which
of these should be "the master bug list?".

If the bugs are kept in a repo, what happens when it changes?
Axiom was originally maintained in CVS and in Arch. Then it
was in SVN, now git. I don't think the bug trackers were
interchangeable.

It just seems reasonable to me to keep the known bugs with
the source code. git allows "disconnected development" because
it is a complete source tree and history. If you're disconnected
you can't reach the bug list on github.

Additionally you maintain your own fork of the project. That
fork will have its own bug trail. If someone forks your code,
shouldn't they also fork the bug list?

It is mildly surprising that the tools to maintain repos (e.g.
git) don't have "git bugnote" or some such support built in.
Or at least a "git bugfetch" to get the current bug list.

Bugs are just another (unintended) developer product.
Of all of the things developers do, they seem to consider
bugs "foreign" despite finding them in every project.
How odd.

 

On Fri, Aug 5, 2016 at 5:18 PM, Ralf Hemmecke <[hidden email]> wrote:
> 6) Bugs are part of the source tree

To me, it would be sufficient, if fixed bug come with a commit message
that describes the bug that is fixed and the source code contains a test
that corresponds to the bug.

I don't necessarily need open bugs in the source tree. They could live
in the same repository (note that git allows non-connected DAGs
(directed acyclic graphs) of commits in one repository), but I wouldn't
want open bugs hanging in the source repo.

Ralf


_______________________________________________
Axiom-developer mailing list
[hidden email]
https://lists.nongnu.org/mailman/listinfo/axiom-developer
Reply | Threaded
Open this post in threaded view
|

Re: Under-appreciated aspects of literate programming

Ralf Hemmecke-4
On 08/06/2016 02:51 AM, Tim Daly wrote:
> Fixed bugs seem uninteresting. Several things failed on my car, for
> instance, that were fixed. There is rarely the need to revisit
> failures, except possibly in regression tests, like brakes :-)

I don't understand your comment. You are in favour of even writing a
book about the bugs in AXIOM and complain about documenting fixed bugs?
Do I misunderstand something?

> Except for release notes, why would anyone want to know about fixed
> bugs? At most someone running an old version might want to know.

Not everyone is always up-to-date with the latest version of the
program. Of course, it would be good if developers can tell of a
misbehaviour of the program is because of the old version and that the
bug is already fixed in a newer version.

Furthermore, a bugfix is not always a bugfix. It might fix the
misbehaviour, but at the same time introduce another misbehaviour,
because the bugfixer did not completely understand that part of the
program. Then it would be good for the next developer (or even for the
same developer---since people tend to forget) to know the underlying
assumptions for the old bugfix.

> On the other hand, a known bug is an intrinsic part of the system
> (mis-)behavior and is something worth noting. Why would you want to
> keep that in, say github?

If you understood my argument, I actually have nothing against putting
bugs into the same repo, but my suggestion is more that they live on a
disconnected DAG and not directly in the DAG of the source code commits.
I think bugs have a different life cycle than source code.

> Axiom has a git repo at savannah, sourceforge, and axiom-developer.
> Which of these should be "the master bug list?".

As with git, one has to declare one to be the master repo. It's only a
small thing to declare one bugtracker as the master. And if the
bugtracker would manage the bugs via git in a separate DAG, then one
could also have the bugs offline. It would probably a bit of a problem
to merge different (half-on/half-offline) discussion lines about a bug,
but I consider that a problem of the specific bugtracker tool.
Unfortunately, I haven't seen a nice and easy to use bugtracker with
underlying git.

> It is mildly surprising that the tools to maintain repos (e.g. git)
> don't have "git bugnote" or some such support built in. Or at least
> a "git bugfetch" to get the current bug list.

True. I think that https://git-scm.com/docs/git-notes is also not the
right thing.

Maybe http://bugseverywhere.org/ is close to what I have in mind, but
I've never tried it and it looks unmaintained (same for ticgit-ng
https://github.com/jeffWelling/ticgit).

Ralf

_______________________________________________
Axiom-developer mailing list
[hidden email]
https://lists.nongnu.org/mailman/listinfo/axiom-developer
Reply | Threaded
Open this post in threaded view
|

Re: Under-appreciated aspects of literate programming

Tim Daly
Methinks I mis-understood your DAG suggestion.

Are you suggesting that the source code is in one DAG
(src/doc/build/etc) and that bugs are in a parallel DAG?

Are you also suggesting that the "bug DAG" be a git repo
separate from the source repo?

In a pile-of-sand (POS) project organized by a directory
structure would it be just as easy to have a bugs directory
in every sub-directory? That would seem to fulfill the goal
but can git have overlapping git-managed directories?

Your bugseverywhere.org link seems to cover most of my
suggestions (except certain LP-specific ones).


On Sat, Aug 6, 2016 at 4:23 AM, Ralf Hemmecke <[hidden email]> wrote:
On 08/06/2016 02:51 AM, Tim Daly wrote:
> Fixed bugs seem uninteresting. Several things failed on my car, for
> instance, that were fixed. There is rarely the need to revisit
> failures, except possibly in regression tests, like brakes :-)

I don't understand your comment. You are in favour of even writing a
book about the bugs in AXIOM and complain about documenting fixed bugs?
Do I misunderstand something?

> Except for release notes, why would anyone want to know about fixed
> bugs? At most someone running an old version might want to know.

Not everyone is always up-to-date with the latest version of the
program. Of course, it would be good if developers can tell of a
misbehaviour of the program is because of the old version and that the
bug is already fixed in a newer version.

Furthermore, a bugfix is not always a bugfix. It might fix the
misbehaviour, but at the same time introduce another misbehaviour,
because the bugfixer did not completely understand that part of the
program. Then it would be good for the next developer (or even for the
same developer---since people tend to forget) to know the underlying
assumptions for the old bugfix.

> On the other hand, a known bug is an intrinsic part of the system
> (mis-)behavior and is something worth noting. Why would you want to
> keep that in, say github?

If you understood my argument, I actually have nothing against putting
bugs into the same repo, but my suggestion is more that they live on a
disconnected DAG and not directly in the DAG of the source code commits.
I think bugs have a different life cycle than source code.

> Axiom has a git repo at savannah, sourceforge, and axiom-developer.
> Which of these should be "the master bug list?".

As with git, one has to declare one to be the master repo. It's only a
small thing to declare one bugtracker as the master. And if the
bugtracker would manage the bugs via git in a separate DAG, then one
could also have the bugs offline. It would probably a bit of a problem
to merge different (half-on/half-offline) discussion lines about a bug,
but I consider that a problem of the specific bugtracker tool.
Unfortunately, I haven't seen a nice and easy to use bugtracker with
underlying git.

> It is mildly surprising that the tools to maintain repos (e.g. git)
> don't have "git bugnote" or some such support built in. Or at least
> a "git bugfetch" to get the current bug list.

True. I think that https://git-scm.com/docs/git-notes is also not the
right thing.

Maybe http://bugseverywhere.org/ is close to what I have in mind, but
I've never tried it and it looks unmaintained (same for ticgit-ng
https://github.com/jeffWelling/ticgit).

Ralf


_______________________________________________
Axiom-developer mailing list
[hidden email]
https://lists.nongnu.org/mailman/listinfo/axiom-developer
Reply | Threaded
Open this post in threaded view
|

Re: Under-appreciated aspects of literate programming

Ralf Hemmecke-4
On 08/06/2016 01:28 PM, Tim Daly wrote:
> Methinks I mis-understood your DAG suggestion.
>
> Are you suggesting that the source code is in one DAG
> (src/doc/build/etc) and that bugs are in a parallel DAG?

More or less yes. I think it is a bit like when you document a project
on github.

https://help.github.com/articles/creating-project-pages-manually/

The gh-pages branch is disconnected from the source code (ie, there are
two DAGs, but they live in the same repository.

> Are you also suggesting that the "bug DAG" be a git repo
> separate from the source repo?

Of course, if that are disjoint DAGs, it's easy to make them live in
different repositories. But git allows to handle several disjoint DAGs
in one repository. (My Definition: A "repository" is simply a collection
of git-objects (and the pointers to form DAGs) under a common name).

> In a pile-of-sand (POS) project organized by a directory
> structure would it be just as easy to have a bugs directory
> in every sub-directory? That would seem to fulfill the goal
> but can git have overlapping git-managed directories?

I don't think that a bug directory in every sub-dir would make sense.
Bugs sometimes touch different parts of a program and usually the
submitter of the bug has no idea, in which part of program the bug might
be hidden.

Otherwise I don't understand "overlapping git-managed directories" to be
able to give a good answer.

> Your bugseverywhere.org <http://bugseverywhere.org> link seems to cover most of my
> suggestions (except certain LP-specific ones).

Well, that's what I found and what (I think) would be good, but read
also
http://travisbrown.ca/blog.html#TooMuchAboutDistributedBugTracking2013-04-20
There are lots of things to consider before one embarks on a particular
distributed bugtracker. Obviously, in contrast to distributed version
control systems, the world hasn't yet seen a great acceptance of
distributed bugtrackers.

Ralf

_______________________________________________
Axiom-developer mailing list
[hidden email]
https://lists.nongnu.org/mailman/listinfo/axiom-developer
Reply | Threaded
Open this post in threaded view
|

Re: Under-appreciated aspects of literate programming

Tim Daly
Hmmm. Your link distinguishes 3 cases, out-of-tree (such as
in a github bug tracker), off-branch (which appears to be what
you are suggesting, right?), and on-branch (part of the sources
in the Axiom scheme).

He raises the question of merging bugs where systems might
have custom software to do things like maintain state (fixed?
diagnosed? open?). In the abstract this is a simple task that
really doesn't need much automation. The github-style out-of-tree
systems seem to have the most (and incompatible) automation.

He also raises issues of distributed bug tracking where there are
multiple sites and/or multiple VCS. This tends to undermine
things like bug state since it is not universal. So any system
that is multiple sites/VCS such as Axiom runs into the state
problem. If there are 3 states on one site and 7 on another,
how are bugs classified?

He raises the problem of a GUI, potentially two versions,
one local and one remote. If there are multiple sites he raises
the distributed database issue. More code, more work, less gain.
Books don't need a GUI, just a PDF reader.

For most of its life Axiom stored bugs in the mailing list.

These were collected into a single "buglist" file a couple years
ago. The recent discussion caused a revisit of the buglist and
made it "first-class" as a literate source, enabling the features
I previously mentioned. Now it is a live object, not just a list of
bug reports and comments.

Axiom's literate version is "on-branch", uses no special state code,
and is "distributed" in that it can be used disconnected since
it is part of the source distribution. It is a single book so there
are no issues about DAGs or directories. Bugs can be attached
to sources (where the connection is known) using hyperlinks
between documents.Bugs can be automatically checked at
build time. I don't see all of these features in any of the DCVS
bug trackers he reviewed.

Everything in Axiom is moving to book form. For example,
Hyperdoc now fetches pages directly from the book, not from
a directory of files. Eventually everything will be in books.So
it makes sense that bugs are literate and cross-linked to the
source books.

Scraping through the forums for bugs is time consuming.
How to handle that collection seems to have many aspects.
Your link seems to have covered them well but he didn't seem
to converge on a solution.




On Sat, Aug 6, 2016 at 6:21 PM, Ralf Hemmecke <[hidden email]> wrote:
On 08/06/2016 01:28 PM, Tim Daly wrote:
> Methinks I mis-understood your DAG suggestion.
>
> Are you suggesting that the source code is in one DAG
> (src/doc/build/etc) and that bugs are in a parallel DAG?

More or less yes. I think it is a bit like when you document a project
on github.

https://help.github.com/articles/creating-project-pages-manually/

The gh-pages branch is disconnected from the source code (ie, there are
two DAGs, but they live in the same repository.

> Are you also suggesting that the "bug DAG" be a git repo
> separate from the source repo?

Of course, if that are disjoint DAGs, it's easy to make them live in
different repositories. But git allows to handle several disjoint DAGs
in one repository. (My Definition: A "repository" is simply a collection
of git-objects (and the pointers to form DAGs) under a common name).

> In a pile-of-sand (POS) project organized by a directory
> structure would it be just as easy to have a bugs directory
> in every sub-directory? That would seem to fulfill the goal
> but can git have overlapping git-managed directories?

I don't think that a bug directory in every sub-dir would make sense.
Bugs sometimes touch different parts of a program and usually the
submitter of the bug has no idea, in which part of program the bug might
be hidden.

Otherwise I don't understand "overlapping git-managed directories" to be
able to give a good answer.

> Your bugseverywhere.org <http://bugseverywhere.org> link seems to cover most of my
> suggestions (except certain LP-specific ones).

Well, that's what I found and what (I think) would be good, but read
also
http://travisbrown.ca/blog.html#TooMuchAboutDistributedBugTracking2013-04-20
There are lots of things to consider before one embarks on a particular
distributed bugtracker. Obviously, in contrast to distributed version
control systems, the world hasn't yet seen a great acceptance of
distributed bugtrackers.

Ralf


_______________________________________________
Axiom-developer mailing list
[hidden email]
https://lists.nongnu.org/mailman/listinfo/axiom-developer