My new workflow
68 views
Skip to first unread message
Edward K. Ream
Oct 30, 2014, 11:58:47 AM10/30/14
to leo-e...@googlegroups.com
For the last several weeks I've used clones in a new, more effective way. This post is pre-writing for a new FAQ entry.
The new workflow was inspired by git's stash/unstash commands. Here are the key ideas.
1. [Most important] I avoid putting clones in two different *external* files.
For any task, I create a task node that resides in @file leoToDo.txt. I clone that node and put it in the outline, *never* in any other @file node. This instantly eliminates clone wars.
2. I use top-level "stashed" nodes/trees in my local copy of leoPy.leo.
These are *not* written to any external file, and so would be lost if I lost leoPy.leo. But the benefits *far* outweigh the risks, and besides, the risks are negligible because all stashed nodes are clones of nodes that *do* exist in external files.
3. I have two main stashed trees: recent files and recent code.
The "recent files" tree contains clones of all the @file nodes I have worked on recently. This speeds up access to them. That happens surprisingly often--often enough to be well worth maintaining the tree. Furthermore, because Leo's new pylint command now works on trees, I can check all recently-changed files simply by running pylint on the "recent files" tree.
The "recent code" tree is even more valuable, for three reasons. The first is obvious--it speeds access to recently-changed nodes.
Second, the "recent code" tree allows me to work on multiple tasks without getting overwhelmed by details and loose nodes lying around. I add organizer nodes as needed to make accessing the nodes faster, and also to jog my memory about what I was doing when I changed those nodes ;-)
Third, the "recent code" tree allows me *not* to put clones in the @file leoProjects.txt tree. This leads me to...
4. I use clones in a stylized way when fixing and committing bugs.
I always use clones when working on a project. A "task" node contains clones of all nodes related to the task. The task node typically remains in leoToDo.txt until the task is completely finished. While working on the bug, I create a clone of the task node, and move that clone to the bottom top-level node of the outline. Among other things, this makes it easy to limit searches without actually choosing "suboutline only" in the Find panel. This workflow is decades old.
The following is the heart of the new workflow. When a task is complete, I do the following:
A. First, I create a **stashed-task** node, containing all the clones that were previously in the task node.
The *stashed-task* becomes pre-writing for the commit log. The *task* node instantly becomes pre-writing for the release notes, so if it needs to discuss any code in the clones that have just been moved to the stashed-task node, I write those words immediately, while all details are fresh in my mind.
B. Now I move the cloned task node that is in leoToDo.txt to the appropriate place in leoProjects.txt.
C. Next I do the commit.
The *other* clone of the task node, and the stashed task node are still within easy reach, and I typically use both nodes to create the commit log. The commit will typically consist of the changed leoToDo.txt and leoProjects.txt and whatever .py files the task itself changed. Happily, leoToDo.txt and leoProjects.txt are now up-to-date because of steps A and B.
D. Finally, I clean up.
I delete the top-level clone of the task node, and move the stashed-task node to the "recent code" tree.
E. Later, when it appears that activity has died down on various projects, I'll delete nodes from the "recent files" an "recent code" trees. This is a minor judgement call: I want to leave nodes in the trees while they are useful, but not significantly longer than that. I do *not* regard these trees as permanently useful. leoProjects.txt should contain *all* permanent notes about a project.
That's it.
===== Conclusion
This is the work flow that I have used to dispatch dozens of bugs recently. I couldn't live without it.
This work flow may seem complicated. Believe me, it is not. It's easier to use than to describe.
This workflow has big advantages:
1. The possibility of clone wars is gone for good.
2. All recent data is easily available.
3. Task nodes and stashed-task nodes provide natural places for proto-documentation.
4. Banning clones from leoProjects.txt forces me to complete the first draft of the documentation before committing the fix.
This work flow has no serious drawbacks. Yes, there is a chance of losing the data in the "recent files" and "recent code" trees, but that would be a minor inconvenience. No data would be lost because essentially everything in the "recent" trees is a clone of data that *does* exist in an external file. Indeed, *not* backing up stashed nodes is useful: only "real" changes get committed to the git repo. There are certainly enough of those changes without committing what is, in effect, transient data. But oh, that transient data comes in handy.
Edward
The new workflow was inspired by git's stash/unstash commands. Here are the key ideas.
1. [Most important] I avoid putting clones in two different *external* files.
For any task, I create a task node that resides in @file leoToDo.txt. I clone that node and put it in the outline, *never* in any other @file node. This instantly eliminates clone wars.
2. I use top-level "stashed" nodes/trees in my local copy of leoPy.leo.
These are *not* written to any external file, and so would be lost if I lost leoPy.leo. But the benefits *far* outweigh the risks, and besides, the risks are negligible because all stashed nodes are clones of nodes that *do* exist in external files.
3. I have two main stashed trees: recent files and recent code.
The "recent files" tree contains clones of all the @file nodes I have worked on recently. This speeds up access to them. That happens surprisingly often--often enough to be well worth maintaining the tree. Furthermore, because Leo's new pylint command now works on trees, I can check all recently-changed files simply by running pylint on the "recent files" tree.
The "recent code" tree is even more valuable, for three reasons. The first is obvious--it speeds access to recently-changed nodes.
Second, the "recent code" tree allows me to work on multiple tasks without getting overwhelmed by details and loose nodes lying around. I add organizer nodes as needed to make accessing the nodes faster, and also to jog my memory about what I was doing when I changed those nodes ;-)
Third, the "recent code" tree allows me *not* to put clones in the @file leoProjects.txt tree. This leads me to...
4. I use clones in a stylized way when fixing and committing bugs.
I always use clones when working on a project. A "task" node contains clones of all nodes related to the task. The task node typically remains in leoToDo.txt until the task is completely finished. While working on the bug, I create a clone of the task node, and move that clone to the bottom top-level node of the outline. Among other things, this makes it easy to limit searches without actually choosing "suboutline only" in the Find panel. This workflow is decades old.
The following is the heart of the new workflow. When a task is complete, I do the following:
A. First, I create a **stashed-task** node, containing all the clones that were previously in the task node.
The *stashed-task* becomes pre-writing for the commit log. The *task* node instantly becomes pre-writing for the release notes, so if it needs to discuss any code in the clones that have just been moved to the stashed-task node, I write those words immediately, while all details are fresh in my mind.
B. Now I move the cloned task node that is in leoToDo.txt to the appropriate place in leoProjects.txt.
C. Next I do the commit.
The *other* clone of the task node, and the stashed task node are still within easy reach, and I typically use both nodes to create the commit log. The commit will typically consist of the changed leoToDo.txt and leoProjects.txt and whatever .py files the task itself changed. Happily, leoToDo.txt and leoProjects.txt are now up-to-date because of steps A and B.
D. Finally, I clean up.
I delete the top-level clone of the task node, and move the stashed-task node to the "recent code" tree.
E. Later, when it appears that activity has died down on various projects, I'll delete nodes from the "recent files" an "recent code" trees. This is a minor judgement call: I want to leave nodes in the trees while they are useful, but not significantly longer than that. I do *not* regard these trees as permanently useful. leoProjects.txt should contain *all* permanent notes about a project.
That's it.
===== Conclusion
This is the work flow that I have used to dispatch dozens of bugs recently. I couldn't live without it.
This work flow may seem complicated. Believe me, it is not. It's easier to use than to describe.
This workflow has big advantages:
1. The possibility of clone wars is gone for good.
2. All recent data is easily available.
3. Task nodes and stashed-task nodes provide natural places for proto-documentation.
4. Banning clones from leoProjects.txt forces me to complete the first draft of the documentation before committing the fix.
This work flow has no serious drawbacks. Yes, there is a chance of losing the data in the "recent files" and "recent code" trees, but that would be a minor inconvenience. No data would be lost because essentially everything in the "recent" trees is a clone of data that *does* exist in an external file. Indeed, *not* backing up stashed nodes is useful: only "real" changes get committed to the git repo. There are certainly enough of those changes without committing what is, in effect, transient data. But oh, that transient data comes in handy.
Edward
Matt Wilkie
Oct 30, 2014, 5:09:37 PM10/30/14
to leo-e...@googlegroups.com
Thank you for sharing this Edward! I often find myself wondering about how others use Leo, even though I've been here awhile now.
I know it wouldn't be soon, lots of other stuff on the go, but this workflow description cries for a screencast or screenshot slideshow. It needn't even be a scripted and rehearsed one like some of the previous ones (because script writing and rehearsal is a lot of work). """You've read the FAQ on "EKR's clone workflow", now watch it [here]. (no sound, BYST, bring your own sound track)"""
...
I know it wouldn't be soon, lots of other stuff on the go, but this workflow description cries for a screencast or screenshot slideshow. It needn't even be a scripted and rehearsed one like some of the previous ones (because script writing and rehearsal is a lot of work). """You've read the FAQ on "EKR's clone workflow", now watch it [here]. (no sound, BYST, bring your own sound track)"""
...
> The "recent files" tree contains clones of all the @file nodes I have worked on recently.
How do you clone @file nodes? Wouldn't that just mean one overwrites the other's external file when saving?
-matt
Fidel N
Oct 31, 2014, 4:01:10 AM10/31/14
to leo-e...@googlegroups.com
While I was reading your description, I was only thinking on how a screencast would be of great use for this.
Then I read Matt comment, so here is my +1.
--
You received this message because you are subscribed to the Google Groups "leo-editor" group.
To unsubscribe from this group and stop receiving emails from it, send an email to leo-editor+...@googlegroups.com.
To post to this group, send email to leo-e...@googlegroups.com.
Visit this group at http://groups.google.com/group/leo-editor.
For more options, visit https://groups.google.com/d/optout.
Edward K. Ream
Oct 31, 2014, 6:30:36 AM10/31/14
to leo-editor
On Thu, Oct 30, 2014 at 4:09 PM, Matt Wilkie <map...@gmail.com> wrote:
> this workflow description cries for a screencast or screenshot slideshow.
I'm pretty much off slideshows :-) I agree, this would be a good screencast.
> this workflow description cries for a screencast or screenshot slideshow.
> How do you clone @file nodes? Wouldn't that just mean one overwrites the
> other's external file when saving?
happens on the second write.
Edward
Reply all
Reply to author
Forward
0 new messages