"revision" considered confusing (was: Outdated Wiki Page?)

[John Yates]

Always happy to beat a dead horse, in this case the confusion
caused by perpetuating the traditional term "revision".  Here
are Eugene's definitions that mention revision:

  Branch:     ordered list of revisions (record of commits)

  Repository: revision storage location

  Revision:   checkpoint in history (state of a working tree as
              recorded by a commit)

  Tag:        descriptive phrase used as a nickname for a revision

Notice the improved clarity when the term revision is dropped
(parentheticals are no longer necessary):

  Branch:     ordered list of commits

  Repository: commit storage location

  Commit:     checkpoint of a working tree

  Tag:        descriptive phrase used as a nickname for a commit

I am not entirely happy with some of these definitions but I did
want to show that preservation of the term revision does nothing
to clarify concepts and definitions.

/john

-----Original Message-----
From: bazaar-bounces at lists.canonical.com
[mailto:bazaar-bounces at lists.canonical.com]On Behalf Of Eugene Wee
Sent: 2007-04-21, Saturday 14:41
To: Aaron Bentley
Cc: bazaar at lists.canonical.com
Subject: Re: Outdated Wiki Page?


Hi,

I think some related pages need to be updated as well. For example, 
http://bazaar-vcs.org/StandaloneBranch reads:
"Standalone branches contain two components: The RCS data and a working 
tree."
This contradicts the statement that:
"If there is no tree, it is called a "standalone branch"."

I would like to add/modify these terms to the glossary 
(http://bazaar-vcs.org/BzrGlossary), and possibly also their individual 
pages. Before I actually do so, are they correct? They are mostly drawn 
from what was recently added to /Branch, and I am hoping to clarify 
rather than misinform and confuse :)

Branch: ordered list of revisions (record of commits)

Checkout: working tree in a separate location from its associated branch

Repository: revision storage location

Repository branch: branch under a repository that may be shared with 
other branches

Revision: checkpoint in history (state of a working tree as recorded by 
a commit)

Shared repository: repository used by multiple branches

Standalone branch: branch without a working tree in the same location

Standalone tree: branch, working tree and repository in the same location

Tag: descriptive phrase used as a nickname for a revision

Working tree: directory with editable files associated with a branch

Regards,
Eugene Wee

Aaron Bentley wrote:
> Dennis Benzinger wrote:
>> Hi!
>>
>> Isn't the note on http://bazaar-vcs.org/Branch outdated?
>> Checkouts and repositories exist at least since 0.15
> 
> Very outdated.  Checkouts and repositories were introduced in 0.8.
> 
> I have done a rewrite to try to make it clearer.  Feel free to improve
> it further.
> 
> Aaron