# # # patch "wiki/BranchNamingConventions.mdwn" # from [c88229100e935c6b3d4a8c572f1455472108b5e0] # to [2fe0a6c1fb2bd2c6e790c957614a39777858dff0] # ============================================================ --- wiki/BranchNamingConventions.mdwn c88229100e935c6b3d4a8c572f1455472108b5e0 +++ wiki/BranchNamingConventions.mdwn 2fe0a6c1fb2bd2c6e790c957614a39777858dff0 @@ -32,11 +32,11 @@ Much more familiar way to represent hier Much more familiar way to represent hierarchical structure. Makes the branch names look like URLs, which may be bad, in that people will expect to be able to browse to them over HTTP, for instance. (Though one could also take advantage of this by actually putting a document there.) Requires escaping branch name '`/`' characters in selectors. -EricAnderson: we use: "domain-name"/"project-name"/"project-branch" for global branches and "email-addr"/"project-name"/"project-branch" for personal branches. The standard for the mainline "project-branch" is just main. The only difference from the above examples is that we standardized on always having three levels in the names, which made things map slightly better onto how people coming from CVS seemed to think about branches. It has an interesting effect of if you do checkouts, they automatically show up in directories organized like the above, which is somewhat nice. However, this auto-directory effect probably wouldn't happen on Windows because the pathname separator on windows is \ not /. We haven't had any problem with people thinking they could browse these. +* > [[People/EricAnderson]]: we use: "domain-name"/"project-name"/"project-branch" for global branches and "email-addr"/"project-name"/"project-branch" for personal branches. The standard for the mainline "project-branch" is just main. The only difference from the above examples is that we standardized on always having three levels in the names, which made things map slightly better onto how people coming from CVS seemed to think about branches. It has an interesting effect of if you do checkouts, they automatically show up in directories organized like the above, which is somewhat nice. However, this auto-directory effect probably wouldn't happen on Windows because the pathname separator on windows is \ not /. We haven't had any problem with people thinking they could browse these. -> [[NathanielSmith]]: Since windows actually accepts both \ and / as directory separators, I think that probably would work after all. +* > [[People/NathanielSmith]]: Since windows actually accepts both \ and / as directory separators, I think that probably would work after all. -Supporters: [[MatthewNicholson]], [[EricAnderson]], [[DanielThompson]] +Supporters: [[People/MatthewNicholson]], [[People/EricAnderson]], [[People/DanielThompson]] ### Hierarchy by : (was "classic mac style") @@ -45,15 +45,15 @@ Suggested by [[People/RichardLevitte]]. Suggested by [[People/RichardLevitte]]. Doesn't look similar to URLs and confuse people, while still allowing a more natural order to things. Requires changes to selector syntax. -*Note by [[People/RichardLevitte]]:* I don't agree that it requires a change to the selector syntax, as a domain name will always have at least one period. +* > *Note by [[People/RichardLevitte]]:* I don't agree that it requires a change to the selector syntax, as a domain name will always have at least one period. -*Note by [[People/ChadWalstrom]]:* I tested this on a Mac OS 10.4.x machine, creating a test branch named address@hidden:blah`. In the shell, the directory was correctly created as address@hidden:blah` upon checkout. It did not create a subdirectory as did the "/" character when chosen as a separator. However, when viewed in the `Finder` application, the directory was listed as address@hidden/blah`. The contradiction in representation of the folder name is confusing. The `Finder` does the correct thing when trying to descend into the directory, however. Practically speaking, this is cosmetic side-effect "bug". +* > *Note by [[People/ChadWalstrom]]:* I tested this on a Mac OS 10.4.x machine, creating a test branch named address@hidden:blah`. In the shell, the directory was correctly created as address@hidden:blah` upon checkout. It did not create a subdirectory as did the "/" character when chosen as a separator. However, when viewed in the `Finder` application, the directory was listed as address@hidden/blah`. The contradiction in representation of the folder name is confusing. The `Finder` does the correct thing when trying to descend into the directory, however. Practically speaking, this is cosmetic side-effect "bug". Supporters: [[People/RichardLevitte]] (obviously) ### Hierarchy by `#` -Example: `[[MyCompanyInc]]#project#branch`, `venge.net#monotone`, `net.venge#monotone#cvssync`, address@hidden +Example: `MyCompanyInc#project#branch`, `venge.net#monotone`, `net.venge#monotone#cvssync`, address@hidden The benefit of this format is that it doesn't really look like a URL and it doesn't require selector character change: `b:venge.net#monotone/a:address@hidden I don't believe this should have any impact on the filesystem checkout, given that the '#' is embedded within the name of the file and should be represented by all locales. Although the '#' is a meta character in POSIX shell for "comment", it does not get parsed as such if there is no space before it. @@ -73,11 +73,11 @@ Cumbersome in general, but makes these f Cumbersome in general, but makes these full-fledged URLs, able to play in all the URL games etc. -[[People/elb]]: I would opt for mtn://, and stick with this -- then allow monotone to connect directly to the named host and fetch the named branch, or allow for a hostname to be provided. This is what opencm did, for whatever that's worth. +* > [[People/elb]]: I would opt for mtn://, and stick with this -- then allow monotone to connect directly to the named host and fetch the named branch, or allow for a hostname to be provided. This is what opencm did, for whatever that's worth. -DanielThompson: I would claim that adding a monotone-specific URL transport into the branch name is a bad idea. Supporting a mtn:// transport command line syntax sugaring for 'monotone pull' (or even 'monotone checkout') would be pleasant but integrating the transport type into the branch name would not assist with this and I would prefer the 'sorta URL style' to a strict URL. +* > [[People/DanielThompson]]: I would claim that adding a monotone-specific URL transport into the branch name is a bad idea. Supporting a mtn:// transport command line syntax sugaring for 'monotone pull' (or even 'monotone checkout') would be pleasant but integrating the transport type into the branch name would not assist with this and I would prefer the 'sorta URL style' to a strict URL. -> [[TimothyBrownawell]]: I would suggest supporting URLs of `mtn://hostname/branchname` . This would provide the convenience of having URLs without the problems of having the transport type or host name be part of the branch name. +* > [[People/TimothyBrownawell]]: I would suggest supporting URLs of `mtn://hostname/branchname` . This would provide the convenience of having URLs without the problems of having the transport type or host name be part of the branch name. ## standard URLs style @@ -87,7 +87,7 @@ May be confusing. May be confusing. -> * [[People/arcatan]]'s thoughts: Let's not use branchs names which look like standard HTTP URLs if they're aren't standard HTTP URLs. If branch is called `http://venge.net/monotone/`, I want to be able to actually pull the repository over HTTP from `http://venge.net/monotone/`, then. +> [[People/arcatan]]'s thoughts: Let's not use branchs names which look like standard HTTP URLs if they're aren't standard HTTP URLs. If branch is called `http://venge.net/monotone/`, I want to be able to actually pull the repository over HTTP from `http://venge.net/monotone/`, then. Supporters: @@ -108,7 +108,7 @@ Suggested by Nathan Myers. Simple, avoid Sorry, that's -[.[.]]@ Suggested by Nathan Myers. Simple, avoids fuss about selectors. Seems unlikely that people will actually register new emails for every branch, and it seems rude to have things that look like email addresses but aren't. -/ + # Selector syntax The basic problem is that selectors currently have both `:` and `/` as magic (meta) characters. These are the two characters that aren't already reserved by the shell (like ```'"!#$&*()<>?;"\|[]%``) or wanted for other things within selectors (like address@hidden which are all likely in email addresses and branch names). @@ -120,8 +120,8 @@ Possible replacement characters include: * `~` -- only magical at the beginning of a shell token * , * possibly ^ -- it is magical in some contexts/some archaic shells, because it was the original pipe symbol. git uses it in a similar context. - * *`%` -- only magical (in Unix) at the beginning of a shell token, no longer common in email addresses.* -- Err, what about on windows, which does env-var substitution like %FOO%? - *Good point. Well, `%%` would avoid that, or choosing a clause separator character not likely to appear in a variable name. (Windows passes the `%...%` construct unmodified if it doesn't match a defined variable).* + * `%` -- only magical (in Unix) at the beginning of a shell token, no longer common in email addresses. -- Err, what about on windows, which does env-var substitution like %FOO%? + * Good point. Well, `%%` would avoid that, or choosing a clause separator character not likely to appear in a variable name. (Windows passes the `%...%` construct unmodified if it doesn't match a defined variable). URL-like things require replacing /, which is used to separate multiple clauses in a selector. So we might end up with: @@ -137,10 +137,16 @@ Stick in your name and your opinion: Stick in your name and your opinion: +* > > [[People/HugoMills]]: The URL/URI-style names have the advantage that things like XML, RDF and OWL all expect such names, so you don't have to mangle or change anything later if one of those technologies is used in some tool. + + > [[People/KennethPerry]]: Also if the URL/URI style names was used, things like a monotone kioslave for KDE would fit (similar to the svn:// kioslave). + +* > [[People/NathanielSmith]]: I kind of like the forms with `~` or `,` as replacements for `/`. The `~` is more visually distinctive, and `,` has already associated meaning of "sequencing" a la [[MagicSelectors]] (but disappears visually more easily). + +* > [[People/ChadWalstrom]]: Branch names should not be transport dependent or interfere with transport naming. I do think it's important to note that that conventions should work *with* but not be enforced *by* the tool, unless it is done via hooks in lua. GNU Arch enforced naming conventions for its branches, which reflected its historical storage mechanism: directories of tarballs containing (uber) patches. This met with a lot of resistance with potential users (and even current users, myself included), especially those not interested in learning the internals and "why's" of naming conventions. + +* > [[People/CraigLennox]]: I favour changing as little as possible while addressing the real problem of namespace overload (which I describe at [Java Style](#JavaStyle) above). This ought to be achievable without having to change the selector syntax. + +* > [[People/gwk]]: Java style (I'm a Java programmer...) it's nice and easy to read and type no shift etc. + +* > [[People/ExampleUser]]: I think [....] - * [[People/HugoMills]]: The URL/URI-style names have the advantage that things like XML, RDF and OWL all expect such names, so you don't have to mangle or change anything later if one of those technologies is used in some tool. - * [[KennethPerry]]: Also if the URL/URI style names was used, things like a monotone kioslave for KDE would fit (similar to the svn:// kioslave). - * [[NathanielSmith]]: I kind of like the forms with `~` or `,` as replacements for `/`. The `~` is more visually distinctive, and `,` has already associated meaning of "sequencing" a la [[MagicSelectors]] (but disappears visually more easily). - * [[People/ChadWalstrom]]: Branch names should not be transport dependent or interfere with transport naming. I do think it's important to note that that conventions should work *with* but not be enforced *by* the tool, unless it is done via hooks in lua. GNU Arch enforced naming conventions for its branches, which reflected its historical storage mechanism: directories of tarballs containing (uber) patches. This met with a lot of resistance with potential users (and even current users, myself included), especially those not interested in learning the internals and "why's" of naming conventions. - * [[People/CraigLennox]]: I favour changing as little as possible while addressing the real problem of namespace overload (which I describe at [Java Style](#JavaStyle) above). This ought to be achievable without having to change the selector syntax. - * [[People/gwk]]: Java style (I'm a Java programmer...) it's nice and easy to read and type no shift etc. - * [[ExampleUser]]: I think [....]