Branches in CVS repository?

Branches in CVS repository?

[Mark Mitchell]

The GCC project allows anyone with write privileges to create branches
in the CVS repository for aribtrary purposes, provided that the usual
guidelines regarding copyrights are followed.  A typical use of these
branches is for distributors to created branches to use for releases,
or for developers to perform experiments.  It's an effective way of
making more information available to people without getting in the way
of the mainline development.

Does the same policy apply to GLIBC and/or Binutils?  If not, could it
be considered?

My particular motivation in this case is the former issue; I would
like to create a branch for a customer release; the branch would
contain backports of patches that apply to this particular customer.
So, if the general policy does not apply, is it permissible for me to
create this particular branch?

--
Mark Mitchell
CodeSourcery, LLC
mark@codesourcery.com

Re: Branches in CVS repository?

[Ian Lance Taylor]

Mark Mitchell <mark@codesourcery.com> writes:

> The GCC project allows anyone with write privileges to create branches
> in the CVS repository for aribtrary purposes, provided that the usual
> guidelines regarding copyrights are followed.  A typical use of these
> branches is for distributors to created branches to use for releases,
> or for developers to perform experiments.  It's an effective way of
> making more information available to people without getting in the way
> of the mainline development.
> 
> Does the same policy apply to GLIBC and/or Binutils?  If not, could it
> be considered?
> 
> My particular motivation in this case is the former issue; I would
> like to create a branch for a customer release; the branch would
> contain backports of patches that apply to this particular customer.
> So, if the general policy does not apply, is it permissible for me to
> create this particular branch?

I don't think that the binutils group has ever developed a plan for
branches.  I don't think anybody has ever wanted to make a binutils
branch other than the ones we make for releases.

Personally I think it is perfectly reasonable to follow the gcc
approach: anybody with write privileges can create a branch, but all
commits to that branch require a copyright assignment just as with all
commits to mainline.

Nick, Alan, any thoughts on this?

Ian

Re: Branches in CVS repository?

[Nick Clifton]

Hi Ian, Hi Mark,

>>The GCC project allows anyone with write privileges to create branches
>>in the CVS repository for aribtrary purposes, provided that the usual
>>guidelines regarding copyrights are followed.  A typical use of these
>>branches is for distributors to created branches to use for releases,
>>or for developers to perform experiments.  It's an effective way of
>>making more information available to people without getting in the way
>>of the mainline development.
>>
>>Does the same policy apply to GLIBC and/or Binutils?  If not, could it
>>be considered?

> I don't think that the binutils group has ever developed a plan for
> branches.  I don't think anybody has ever wanted to make a binutils
> branch other than the ones we make for releases.
> 
> Personally I think it is perfectly reasonable to follow the gcc
> approach: anybody with write privileges can create a branch, but all
> commits to that branch require a copyright assignment just as with all
> commits to mainline.
> 
> Nick, Alan, any thoughts on this?

I agree.  I can no reason to block this kind of behaviour and good 
reasons to encourage it.  So yes, I think that Mark should go ahead and 
create his branch.  In fact if he would like to propose a paragraph to 
be added to binutils/MAINTAINERS that we be welcome as well.

Cheers
   Nick

Re: Branches in CVS repository?

[Mark Mitchell]

Nick Clifton wrote:

> I agree.  I can no reason to block this kind of behaviour and good 
> reasons to encourage it.  So yes, I think that Mark should go ahead and 
> create his branch.  In fact if he would like to propose a paragraph to 
> be added to binutils/MAINTAINERS that we be welcome as well.

In thinking about this a bit further, I realize that the issue is 
complicated by the fact that binutils is part of the whole src/ 
repository.  A branch created just in the binutils portion might be 
confusing, and, in any case, doing something like a new assembler port 
requires changes to other parts of the tree as well to support new 
opcodes and such.  I'm happy to go ahead with the binutils/MAINTAINERS 
changes, but I wonder if we should get some kind of more global policy 
set for the entire src/ repository.  Thoughts?

-- 
Mark Mitchell
CodeSourcery, LLC
mark@codesourcery.com
(916) 791-8304

Re: Branches in CVS repository?

[Andreas Schwab]

Mark Mitchell <mark@codesourcery.com> writes:

> In thinking about this a bit further, I realize that the issue is
> complicated by the fact that binutils is part of the whole src/
> repository.  A branch created just in the binutils portion might be
> confusing, and, in any case, doing something like a new assembler port
> requires changes to other parts of the tree as well to support new opcodes
> and such.

You only need to check out the binutils module.

Andreas.

-- 
Andreas Schwab, SuSE Labs, schwab@suse.de
SuSE Linux Products GmbH, Maxfeldstraße 5, 90409 Nürnberg, Germany
Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: Branches in CVS repository?

[Mark Mitchell]

Andreas Schwab wrote:
> Mark Mitchell <mark@codesourcery.com> writes:
> 
> 
>>In thinking about this a bit further, I realize that the issue is
>>complicated by the fact that binutils is part of the whole src/
>>repository.  A branch created just in the binutils portion might be
>>confusing, and, in any case, doing something like a new assembler port
>>requires changes to other parts of the tree as well to support new opcodes
>>and such.
> 
> 
> You only need to check out the binutils module.

Yes, but it contains code from other subdirectories.  For example, it 
contains all the files in the top level directory, the stuff in intl/, 
the stuff in libiberty/, and the stuff in opcodes/.  A branch made in 
the tree I checked out for binutils will create branches in all of these 
places.  So, we need to get agreement that it's OK to create branches in 
those directories as well.

-- 
Mark Mitchell
CodeSourcery, LLC
mark@codesourcery.com
(916) 791-8304

Re: Branches in CVS repository?

[DJ Delorie]

I don't have a problem with branches in src/libiberty or src/include,
provided it's understood that those branches exist for - or at least
conflict with - all the projects using those directories.  A global
naming convention would be nice.

Re: Branches in CVS repository?

[Andreas Schwab]

Mark Mitchell <mark@codesourcery.com> writes:

> Yes, but it contains code from other subdirectories.  For example, it
> contains all the files in the top level directory, the stuff in intl/, the
> stuff in libiberty/, and the stuff in opcodes/.  A branch made in the tree
> I checked out for binutils will create branches in all of these places.
> So, we need to get agreement that it's OK to create branches in those
> directories as well.

All those directories and files are part of binutils.  Just because you
add a branch tag does not mean that you necessarily modify those files.

Andreas.

-- 
Andreas Schwab, SuSE Labs, schwab@suse.de
SuSE Linux Products GmbH, Maxfeldstraße 5, 90409 Nürnberg, Germany
Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: Branches in CVS repository?

[Mark Mitchell]

Andreas Schwab wrote:
> Mark Mitchell <mark@codesourcery.com> writes:
> 
> 
>>Yes, but it contains code from other subdirectories.  For example, it
>>contains all the files in the top level directory, the stuff in intl/, the
>>stuff in libiberty/, and the stuff in opcodes/.  A branch made in the tree
>>I checked out for binutils will create branches in all of these places.
>>So, we need to get agreement that it's OK to create branches in those
>>directories as well.
> 
> 
> All those directories and files are part of binutils.  Just because you
> add a branch tag does not mean that you necessarily modify those files.

I'm certainly not trying to make things hard, but I'm surprised to hear 
you say that "intl/" and "libiberty/" are part of binutils.  They're 
included in it, but, in my experience, DJ has not appreciated people 
making changes to libiberty/ without his approval.

One point of view here is that creating a branch, and then, perhaps, 
making modifications on the branch should not concern the original 
maintainers as you're not getting in their way.  I'm happy with that 
point of view, but I would like to see everyone agree on it.  I'd rather 
not go creating a branch and then find that people object.

Anyhow, since it seems like all the people involved in this discussion 
(with the exception of the still-slient libc folks) are in agreement 
that creating such a branch is OK, let's try to settle on a naming 
convention.

The informal GCC convention has been "<org>-<name>" where "org" is the 
initials of the organization creating the branch.  For "CodeSourcery, 
LLC" that would be "csl"; for "Red Hat" it would be "rh".  For an 
individual "Mark Patrick Mitchell" it would be "mpm".  Then, the "name" 
is some organization-specific description of the branch.  For example, 
"csl-arm" would be a CodeSourcery branch for doing ARM development. 
Does that sound OK to everyone?

-- 
Mark Mitchell
CodeSourcery, LLC
mark@codesourcery.com
(916) 791-8304

Re: Branches in CVS repository?

[DJ Delorie]

> The informal GCC convention has been "<org>-<name>" where "org" is the 

RH's internal convention includes a YYMMDD somewhere, which is
especially useful for long lived projects that have to rebranch often.
Perhaps an optional <org>-<name>-<date> should be allowed, for when
people suspect that would be useful.

Re: Branches in CVS repository?

[Mark Mitchell]

DJ Delorie wrote:
>>The informal GCC convention has been "<org>-<name>" where "org" is the 
> 
> 
> RH's internal convention includes a YYMMDD somewhere, which is
> especially useful for long lived projects that have to rebranch often.
> Perhaps an optional <org>-<name>-<date> should be allowed, for when
> people suspect that would be useful.

I'd meant to allow arbitrary characters in "name", which would certainly 
permit what you suggest.

-- 
Mark Mitchell
CodeSourcery, LLC
mark@codesourcery.com
(916) 791-8304

Re: Branches in CVS repository?

[Nick Clifton]

Hi Guys,

>>> The informal GCC convention has been "<org>-<name>" where "org" is the 

>> RH's internal convention includes a YYMMDD somewhere, which is

> I'd meant to allow arbitrary characters in "name", which would certainly 
> permit what you suggest.

But it is best to be explicit.  How about:

   <module(s)>-<org>-<reason>-<date>

eg:

   binutils-csl-ARM_development-050118

which may be a little bit wordy, but should avoid all possibility if 
name space collisions and should make the purpose of the branch obvious.

Cheers
   Nick

Re: Branches in CVS repository?

[Mark Mitchell]

Nick Clifton wrote:
> Hi Guys,
> 
>>>> The informal GCC convention has been "<org>-<name>" where "org" is the 
> 
> 
>>> RH's internal convention includes a YYMMDD somewhere, which is
> 
> 
>> I'd meant to allow arbitrary characters in "name", which would 
>> certainly permit what you suggest.
> 
> 
> But it is best to be explicit.  How about:
> 
>   <module(s)>-<org>-<reason>-<date>
> 
> eg:
> 
>   binutils-csl-ARM_development-050118
> 
> which may be a little bit wordy, but should avoid all possibility if 
> name space collisions and should make the purpose of the branch obvious.

I don't quite understand the date part.  Is this because we might merge 
our changes forward to a new basepoint (like the 050221 mainline 
version) later?  Our usual practice has been to merge the delta between 
050118 and 050221 onto our branch, rather than create a new branch.  May 
we make the date optional?

-- 
Mark Mitchell
CodeSourcery, LLC
mark@codesourcery.com
(916) 791-8304

Re: Branches in CVS repository?

[Nick Clifton]

Hi Mark,

>> But it is best to be explicit.  How about:
>>
>>   <module(s)>-<org>-<reason>-<date>
>>
>> eg:
>>
>>   binutils-csl-ARM_development-050118

> I don't quite understand the date part.  Is this because we might merge 
> our changes forward to a new basepoint (like the 050221 mainline 
> version) later?

No, I was suggesting the date part for two reasons:

   * It documents when the branch was started without having to look in 
the logs.  This can be helpful if multiple possible branches are 
available to the developer and they want to choose the most recent one.

   * It allows future branches with the same purpose to be created.  For 
example suppose that CodeSourcery completed their work on the 
binutils-csl-ARM_development-050118 branch and merged the results back 
into the mainline.  Then a year later ARM comes back to CodeSourcery and 
says "we liked the work you did so much, here is a new contract". 
Rather than starting with the binutils-csl-ARM_development-050118-branch 
and having to backport all of the changes that have been made in the 
mainline since then you can simply create a new branch 
"binutils-csl-ARM_development-070101-branch".


> May we make the date optional?

We could, if you can convince me that it is unneeded.  At the moment I 
still think that it is useful.

Cheers
   Nick

Re: Branches in CVS repository?

[Mark Mitchell]

Nick Clifton wrote:

>> May we make the date optional?
> 
> 
> We could, if you can convince me that it is unneeded.  At the moment I 
> still think that it is useful.

I don't debate that it will be useful to you.

But if it's not useful to someone else, and they're already operating in 
a separate tag namespace, why is it important to you?

It's not that I can't add a date on the end of every branch; it's just 
that I don't particularly want to, and I don't see how that helps the 
broader community.  (What I would imagine helpful is requiring people to 
document the branches they've created.)

Thanks,

-- 
Mark Mitchell
CodeSourcery, LLC
mark@codesourcery.com
(916) 791-8304

Re: Branches in CVS repository?

[Nick Clifton]

Hi Mark,

>> We could, if you can convince me that it is unneeded.  At the moment I 
>> still think that it is useful.

> But if it's not useful to someone else, and they're already operating in 
> a separate tag namespace, why is it important to you?

Presumably you mean "a separate tag namespace when creating branches for 
other projects" ?

The reason I think that it is important is that I think that we ought to 
  have a documented and useful naming scheme for branches created in 
connection with the binutils project.  In my opinion having that date of 
the branch creating be part of the name of the branch is useful and that 
is why I am suggesting it.  If however nobody else feels that way then I 
  not going to insist upon them.  The date can always be discovered by 
trawling the logs.


> It's not that I can't add a date on the end of every branch; it's just 
> that I don't particularly want to, and I don't see how that helps the 
> broader community.

Fair enough - if I am the only one who thinks that these dates would be 
helpful then I am not going to insist on them.

> (What I would imagine helpful is requiring people to 
> document the branches they've created.)

Agreed.

Cheers
   Nick

RE: Branches in CVS repository?

[Dave Korn]

> -----Original Message-----
> From: binutils-owner On Behalf Of Nick Clifton
> Sent: 19 January 2005 16:11

> Hi Mark,
> 
> >> We could, if you can convince me that it is unneeded.  At 
> the moment I 
> >> still think that it is useful.
> 
> > But if it's not useful to someone else, and they're already 
> operating in 
> > a separate tag namespace, why is it important to you?
> 
> Presumably you mean "a separate tag namespace when creating 
> branches for other projects" ?

  I think he's suggesting that the -<org>- part of the tag would suffice to
distinguish the namespaces even within the same <module>-, and the
least-significant word(s) of the tag that follows -<org>- could conform to any
format that those within -<org>- decided suited their needs without any danger
of clashing between -<org1>-'s namespace and -<org2>-'s.

  <module>-<org>-<org-dependent-part>

  No reason why <org-dependent-part> shouldn't amount to -<date> for -<org>- ==
-rh- and to -<somethingelse> when -<org>- == -cs-

    cheers, 
      DaveK
-- 
Can't think of a witty .sigline today....

Re: Branches in CVS repository?

[Mark Mitchell]

Nick Clifton wrote:
> Hi Mark,
> 
>>> We could, if you can convince me that it is unneeded.  At the moment 
>>> I still think that it is useful.
> 
> 
>> But if it's not useful to someone else, and they're already operating 
>> in a separate tag namespace, why is it important to you?
> 
> 
> Presumably you mean "a separate tag namespace when creating branches for 
> other projects" ?

Yes; I was meaning that if we agree on the "<project>-<org>-<name>" 
style (where "<name>" may have additional structure, such as your 
"<name>-<date>" suggestion), then we can already be sure that 
CodeSourcery's tags will not conflict with Red Hat's tags, for example.

> Fair enough - if I am the only one who thinks that these dates would be 
> helpful then I am not going to insist on them.

OK; I'm of the symmetric opinion: if the policy is to add the dates, I 
will certainly respect that, but I'd prefer not to do so.

I suggest the following: I'll prepare a patch for binutils/MAINTAINERS 
that explains the policy, and submit it.  When I do that, you can decide 
whether you want to require the <date> portion of the branch name, and, 
if so, I will adjust the MAINTAINERS file before committing.  Is that a 
reasonable way to proceed?

-- 
Mark Mitchell
CodeSourcery, LLC
mark@codesourcery.com
(916) 791-8304

Re: Branches in CVS repository?

[Nick Clifton]

Hi Mark,

> I suggest the following: I'll prepare a patch for binutils/MAINTAINERS 
> that explains the policy, and submit it.  When I do that, you can decide 
> whether you want to require the <date> portion of the branch name, and, 
> if so, I will adjust the MAINTAINERS file before committing.  Is that a 
> reasonable way to proceed?

Yes - that would be excellent.

Cheers
   Nick

Re: Branches in CVS repository?

[Mark Mitchell]

[-- Attachment #1: Type: text/plain, Size: 531 bytes --]

Nick Clifton wrote:
> Hi Mark,
> 
>> I suggest the following: I'll prepare a patch for binutils/MAINTAINERS 
>> that explains the policy, and submit it.  When I do that, you can 
>> decide whether you want to require the <date> portion of the branch 
>> name, and, if so, I will adjust the MAINTAINERS file before 
>> committing.  Is that a reasonable way to proceed?
> 
> 
> Yes - that would be excellent.

OK, here's an attempt.  Thoughts?  OK to commit?

-- 
Mark Mitchell
CodeSourcery, LLC
mark@codesourcery.com
(916) 791-8304

[-- Attachment #2: binutils.patch --]
[-- Type: text/plain, Size: 2966 bytes --]

Index: MAINTAINERS
===================================================================
RCS file: /cvs/src/src/binutils/MAINTAINERS,v
retrieving revision 1.78
diff -c -5 -p -r1.78 MAINTAINERS
*** MAINTAINERS	16 Jan 2005 23:47:40 -0000	1.78
--- MAINTAINERS	19 Jan 2005 17:03:22 -0000
*************** Patches to the top level configure files
*** 166,170 ****
--- 166,221 ----
  are not the domain of the binutils project and they cannot be approved
  by the binutils group.  Instead they should be submitted to the config
  maintainer at:
  
  	config-patches@gnu.org
+ 
+     --------- Creating Branches ---------
+ 
+ Anyone with at least write-after-approval access may create a branch
+ to use for their own development purposes.  In keeping with FSF
+ policies, all patches applied to such a branch must come from people
+ with appropriate copyright assignments on file.  
+ 
+ Before creating the branch, you should select a name for the branch of
+ the form:
+ 
+   binutils-<org>-<name> 
+ 
+ where "org" is the initials of your organization, or your own initials
+ if you are acting as an individual.  For example, for a branch created
+ by The GNUDist Company, "tgc" would be an appropriate choice for
+ "org".  It's up to each organization to select an appropriate choice
+ for "name"; some organizations may use more structure than others, so
+ "name" may contain additional hyphens.
+ 
+ Suppose that The GNUDist Company was creating a branch to develop a
+ port of Binutils to the FullMonty processor.  Then, an appropriate
+ choice of branch name would be:
+ 
+   binutils-tgc-fm
+ 
+ Having selected the branch name, create the branch as follows:
+ 
+ 1. Check out binutils, so that you have a CVS checkout corresponding
+    to the initial state of your branch.
+ 
+ 2. Create a tag:
+ 
+      cvs tag binutils-<org>-<name>-branchpoint
+ 
+    That tag will allow you, and others, to easily determine what's
+    changed on the branch relative to the initial state.
+ 
+ 3. Create the branch:
+ 
+      cvs rtag -b -r binutils-<org>-<name>-branchpoint \
+        binutils-<org>-<name>-branch 
+ 
+ 4. Document the branch:
+ 
+      Add a description of the branch to BRANCHES, and check that file
+      in.  All branch descriptions should be added to the HEAD revision
+      of the file; it doesn't help to modify BRANCHES on a branch!
+ 
+ Please do not commit any patches to a branch you did not create
+ without the explicit permission of the person who created the branch.
Index: BRANCHES
===================================================================
RCS file: BRANCHES
diff -N BRANCHES
*** /dev/null	1 Jan 1970 00:00:00 -0000
--- BRANCHES	19 Jan 2005 17:03:22 -0000
***************
*** 0 ****
--- 1,9 ----
+ Please keep the following tables alphabetical.
+ 
+ Organization		Organization Name
+ ------------		-----------------
+ tgc			The GNUDist Company	
+ 	
+ Branch			Description
+ ------			-----------
+ binutils-tgc-fm		FullMonty port

Re: Branches in CVS repository?

[Richard Earnshaw]

On Wed, 2005-01-19 at 17:50, Mark Mitchell wrote:

> OK, here's an attempt.  Thoughts?  OK to commit?

+ 4. Document the branch:
+ 
+      Add a description of the branch to BRANCHES, and check that file
+      in.  All branch descriptions should be added to the HEAD revision
+      of the file; it doesn't help to modify BRANCHES on a branch!

The documentation needs to describe the commit policy and the 'owner' of
the branch -- commit policy might be a list of who can approve patches,
etc.  The owner makes it fully clear who owns the branch, ideally with a
name and contact address.

+ 
+ Please do not commit any patches to a branch you did not create
+ without the explicit permission of the person who created the branch.

'Branch owner' might be more appropriate here; or given the above
change, 'only changes consistent with the commit policy for the branch
may be checked in'.

It might be worth adding a further note that no code may be committed on
a branch that could not be legally distributed as part of a normal
public release, or something to that effect.  That doesn't imply that
the FSF would necessarily want to do that, but it does mean they could
if they so wanted.   Implication: if you don't want to permit that, then
it doesn't belong in the FSF source repository.

R.

Re: Branches in CVS repository?

[Mark Mitchell]

Richard Earnshaw wrote:
> On Wed, 2005-01-19 at 17:50, Mark Mitchell wrote:
> 
> 
>>OK, here's an attempt.  Thoughts?  OK to commit?
> 
> 
> + 4. Document the branch:

...

> + 
> + Please do not commit any patches to a branch you did not create
> + without the explicit permission of the person who created the branch.
> 
...

Good comments.  I'll revise, but I'll wait to see if Nick et. al. have 
other comments, so that I can batch them all together.

-- 
Mark Mitchell
CodeSourcery, LLC
mark@codesourcery.com
(916) 791-8304

Re: Branches in CVS repository?

[Paul Brook]

On Wednesday 19 January 2005 17:50, Mark Mitchell wrote:
> + Please keep the following tables alphabetical.
> +
> + Organization          Organization Name
> + ------------          -----------------
> + tgc                   The GNUDist Company     
> +       
> + Branch                        Description
> + ------                        -----------
> + binutils-tgc-fm               FullMonty port

Do we want to distinguish between active and inactive branches?

Maybe also have release branches mentioned somewhere for completeness.

Paul

Re: Branches in CVS repository?

[Mark Mitchell]

Paul Brook wrote:
> On Wednesday 19 January 2005 17:50, Mark Mitchell wrote:
> 
>>+ Please keep the following tables alphabetical.
>>+
>>+ Organization          Organization Name
>>+ ------------          -----------------
>>+ tgc                   The GNUDist Company     
>>+       
>>+ Branch                        Description
>>+ ------                        -----------
>>+ binutils-tgc-fm               FullMonty port
> 
> 
> Do we want to distinguish between active and inactive branches?

I'm not sure I even know for sure when a branch is active/inactive; 
sometimes, you end up going back to a very old branch if someone wants 
to add just one fix there.

> Maybe also have release branches mentioned somewhere for completeness.

Yes, we could add them here too.  I'll mention the naming convention in 
use for binutils release branches, so that we make sure not to step on them.

-- 
Mark Mitchell
CodeSourcery, LLC
mark@codesourcery.com
(916) 791-8304

Re: Branches in CVS repository?

[Mark Mitchell]

[-- Attachment #1: Type: text/plain, Size: 366 bytes --]

Here is the version I checked in, following Nick's instructions.

I put the BRANCHES file in binutils/, since that's what Nick approved, 
and I'm not sure who could approve putting it at top level.  I'm happy 
to move it, if necessary.  If more changes need to be made, let me know.

Thanks,

-- 
Mark Mitchell
CodeSourcery, LLC
mark@codesourcery.com
(916) 791-8304

[-- Attachment #2: binutils.patch --]
[-- Type: text/plain, Size: 4033 bytes --]

Index: MAINTAINERS
===================================================================
RCS file: /cvs/src/src/binutils/MAINTAINERS,v
retrieving revision 1.78
diff -c -5 -p -r1.78 MAINTAINERS
*** MAINTAINERS	16 Jan 2005 23:47:40 -0000	1.78
--- MAINTAINERS	20 Jan 2005 21:58:02 -0000
*************** Patches to the top level configure files
*** 166,170 ****
--- 166,238 ----
  are not the domain of the binutils project and they cannot be approved
  by the binutils group.  Instead they should be submitted to the config
  maintainer at:
  
  	config-patches@gnu.org
+ 
+     --------- Creating Branches ---------
+ 
+ Anyone with at least write-after-approval access may create a branch
+ to use for their own development purposes.  In keeping with FSF
+ policies, all patches applied to such a branch must come from people
+ with appropriate copyright assignments on file.  All legal
+ requirements that would apply to any other contribution apply equally
+ to contributions on a branch.
+ 
+ Before creating the branch, you should select a name for the branch of
+ the form:
+ 
+   binutils-<org>-<name> 
+ 
+ where "org" is the initials of your organization, or your own initials
+ if you are acting as an individual.  For example, for a branch created
+ by The GNUDist Company, "tgc" would be an appropriate choice for
+ "org".  It's up to each organization to select an appropriate choice
+ for "name"; some organizations may use more structure than others, so
+ "name" may contain additional hyphens.
+ 
+ Suppose that The GNUDist Company was creating a branch to develop a
+ port of Binutils to the FullMonty processor.  Then, an appropriate
+ choice of branch name would be:
+ 
+   binutils-tgc-fm
+ 
+ A data stamp is not required as part of the name field, but some
+ organizations like to have one.  If you do include the date, you
+ should follow these rules:
+ 
+ 1. The date should be the date that the branch was created.
+ 
+ 2. The date should be numerical and in the form YYYYMMDD.
+ 
+ For example:
+ 
+   binutils-tgc-fm_20050101
+ 
+ would be appropriate if the branch was created on January 1st, 2005.
+ 
+ Having selected the branch name, create the branch as follows:
+ 
+ 1. Check out binutils, so that you have a CVS checkout corresponding
+    to the initial state of your branch.
+ 
+ 2. Create a tag:
+ 
+      cvs tag binutils-<org>-<name>-branchpoint
+ 
+    That tag will allow you, and others, to easily determine what's
+    changed on the branch relative to the initial state.
+ 
+ 3. Create the branch:
+ 
+      cvs rtag -b -r binutils-<org>-<name>-branchpoint \
+        binutils-<org>-<name>-branch 
+ 
+ 4. Document the branch:
+ 
+      Add a description of the branch to binutils/BRANCHES, and check
+      that file in.  All branch descriptions should be added to the
+      HEAD revision of the file; it doesn't help to modify
+      binutils/BRANCHES on a branch!
+ 
+ Please do not commit any patches to a branch you did not create
+ without the explicit permission of the person who created the branch.
Index: BRANCHES
===================================================================
RCS file: BRANCHES
diff -N BRANCHES
*** /dev/null	1 Jan 1970 00:00:00 -0000
--- BRANCHES	20 Jan 2005 21:58:02 -0000
***************
*** 0 ****
--- 1,22 ----
+ Please keep the following tables alphabetical.
+ 
+ Organization Tag	Organization Name
+ ----------------	-----------------
+ csl			CodeSourcery, LLC	
+ 
+ This table lists branches created by particular organizations.  Please
+ include the branch name, and a description of the branch.  The branch
+ description should name the owner of the branch (i.e., the person to
+ contact regarding the branch) and a description of the commit policy
+ for the branch (e.g., "no commits without permission of X or Y").
+ 	
+ Organization Branches	Description
+ ---------------------	-----------
+ 
+ Release Branches
+ ----------------
+ binutils-2_10-branch
+ binutils-2_11-branch
+ binutils-2_12-branch
+ binutils-2_13-branch
+ binutils-2_14-branch

Re: Branches in CVS repository?

[Eric Botcazou]

+ Release Branches
+ ----------------
+ binutils-2_10-branch
+ binutils-2_11-branch
+ binutils-2_12-branch
+ binutils-2_13-branch
+ binutils-2_14-branch

Any specific reason for omitting binutils-2_15-branch?

-- 
Eric Botcazou

Re: Branches in CVS repository?

[Mark Mitchell]

Eric Botcazou wrote:
> + Release Branches
> + ----------------
> + binutils-2_10-branch
> + binutils-2_11-branch
> + binutils-2_12-branch
> + binutils-2_13-branch
> + binutils-2_14-branch
> 
> Any specific reason for omitting binutils-2_15-branch?

No, I was just being a reject.  I've checked in the obvious patch.

-- 
Mark Mitchell
CodeSourcery, LLC
mark@codesourcery.com
(916) 791-8304

Re: Branches in CVS repository?

[DJ Delorie]

> I put the BRANCHES file in binutils/, since that's what Nick approved, 
> and I'm not sure who could approve putting it at top level.  I'm happy 
> to move it, if necessary.  If more changes need to be made, let me know.

My guesses would be: Andrew for GDB, Jeff for newlib, Chris for
cygwin.  Toplevel certainly has *my* approval, for what that's worth.

I just don't see how putting it in a binutils-specific place is going
to solve the problem of coordinating branches across all the src/
projects.

Re: Branches in CVS repository?

[Christopher Faylor]

On Thu, Jan 20, 2005 at 05:38:44PM -0500, DJ Delorie wrote:
>> I put the BRANCHES file in binutils/, since that's what Nick approved, 
>> and I'm not sure who could approve putting it at top level.  I'm happy 
>> to move it, if necessary.  If more changes need to be made, let me know.
>
>My guesses would be: Andrew for GDB, Jeff for newlib, Chris for
>cygwin.  Toplevel certainly has *my* approval, for what that's worth.
>
>I just don't see how putting it in a binutils-specific place is going
>to solve the problem of coordinating branches across all the src/
>projects.

I've been following the discussion but I don't have any real preferences
one way or the other as far as cygwin is concerned.  I think it's
unlikely that anyone is going to want to branch cygwin, though.

I'll chime in if I have strong objections, but I haven't had any so far.
If you don't hear from me, it's safe to assume I'm ok with the current
plan.

cgf

Re: Branches in CVS repository?

[Nick Clifton]

Hi Guys,

>>I put the BRANCHES file in binutils/, since that's what Nick approved, 
>>and I'm not sure who could approve putting it at top level.  I'm happy 
>>to move it, if necessary.  If more changes need to be made, let me know.

I certainly don't object to BRANCHES being at the top level, I just felt 
that it would be confusing to have MAINTAINERS in the binutils/ 
directory and BRANCHES in the top level.  Perhaps it would be better to 
move the MAINTAINERS file to the top level and rename it 
MAINTAINERS.binutils ?

Alternatively we could have a small top level BRANCHES file that just 
says something like:

   "For descriptions of per-project branches in the CVS repository see
    these project specific files:

     binutils:   binutils/BRANCHES
     GDB         ???
     cygwin      ???
     libiberty   ???

    If the file does not exist it means that project specific
    branches have yet to be created."


Cheers
   Nick

Re: Branches in CVS repository?

[DJ Delorie]

> I certainly don't object to BRANCHES being at the top level, I just felt 
> that it would be confusing to have MAINTAINERS in the binutils/ 
> directory and BRANCHES in the top level.

Maintainers are project-scope.  Branches are repository-scope.  I see
no reason why they would have to be in the same directory.

Putting a "branch list found here" file in toplevel means that
developers will always need to check out and read ALL the src projects
just to find out what the branches are.

Re: Branches in CVS repository?

[DJ Delorie]

> Putting a "branch list found here" file in toplevel means that
> developers will always need to check out and read ALL the src
> projects just to find out what the branches are.

Also, part of, but not all, of the branch information would have to be
replicated to all the projects, whether you have checkin permission or
not.  It would be a maintenance nightmare.

Re: Branches in CVS repository?

[Nick Clifton]

Hi DJ,

>>Putting a "branch list found here" file in toplevel means that
>>developers will always need to check out and read ALL the src
>>projects just to find out what the branches are.
> 
> 
> Also, part of, but not all, of the branch information would have to be
> replicated to all the projects, whether you have checkin permission or
> not.  It would be a maintenance nightmare.

OK then lets out it at the top level.

Cheers
   Nick

Re: Branches in CVS repository?

[Mark Mitchell]

Nick Clifton wrote:
> Hi DJ,
> 
>>> Putting a "branch list found here" file in toplevel means that
>>> developers will always need to check out and read ALL the src
>>> projects just to find out what the branches are.
>>
>>
>>
>> Also, part of, but not all, of the branch information would have to be
>> replicated to all the projects, whether you have checkin permission or
>> not.  It would be a maintenance nightmare.
> 
> 
> OK then lets out it at the top level.

Does that mean we should move the MAINTAINERS information I wrote to the 
top level too?  I can easiy reword it not to be binutils-specific if we 
think this is now a project-wide consensus.

-- 
Mark Mitchell
CodeSourcery, LLC
mark@codesourcery.com
(916) 791-8304

Re: Branches in CVS repository?

[DJ Delorie]

> Does that mean we should move the MAINTAINERS information I wrote to the 
> top level too?  I can easiy reword it not to be binutils-specific if we 
> think this is now a project-wide consensus.

I suspect a better plan is to document the branch policy in the
BRANCHES file itself.

Re: Branches in CVS repository?

[Andrew Cagney]

>>Does that mean we should move the MAINTAINERS information I wrote to the 
>>top level too?  I can easiy reword it not to be binutils-specific if we 
>>think this is now a project-wide consensus.

This is a binutils policy, it was discussed and established on a 
binutils list.  Other projects (GCC, GDB) already have established 
branch policies.

> I suspect a better plan is to document the branch policy in the
> BRANCHES file itself.

Andrew

Re: Branches in CVS repository?

[Nick Clifton]

Hi Mark,

> OK, here's an attempt.  Thoughts?  OK to commit?

Yes, with the changes already suggested by others.  I would suggest the 
following however:

   * Where do you envisage the BRANCHES file living ?  In the top level 
directory or in the binutils/ subdirectory ?  I would assume the latter, 
in which case I think that you ought to refer to the file as 
binutils/BRANCHES in the binutils/MAINTAINERS file, just so that there 
is no confusion about the location.

   * We might as well be clear about the issue of dates in branch tags. 
  Thus I would suggest adding this after the binutils-tgc-fm example:

   "A date stamp is not required as part of the name field, but some 
organizations like to have one.  If you do include the date it should 
follow these rules:

    1.  The date should be the date that the branch was created.
    2.  The date should be numerical and in the form YYYYMMDD.

For example

    binutils-tgc-fm_20050101"

Cheers
   Nick

Re: Branches in CVS repository?

[DJ Delorie]

>    * Where do you envisage the BRANCHES file living ?  In the top level 
> directory or in the binutils/ subdirectory ?  I would assume the latter, 

Toplevel.  The whole point of this problem is that branches are global
resources.

Re: Branches in CVS repository?

[Andrew Cagney]

> Fair enough - if I am the only one who thinks that these dates would be 
> helpful then I am not going to insist on them.

Yes, agreed, the date is very helpful (it should be YYYYMMDD).  It's 
especially helpful when identifying exact branch and merge points - the 
nature of cvs is such that "cvs log" is not exact.  Besides, there's 
nothing to stop the person cutting the branch from using "cvs admin" to 
create a shorter alias for the currently active longer tag.

Andrew

Re: Branches in CVS repository?

[Richard Earnshaw]

On Wed, 2005-01-19 at 20:28, Andrew Cagney wrote:
> > Fair enough - if I am the only one who thinks that these dates would be 
> > helpful then I am not going to insist on them.
> 
> Yes, agreed, the date is very helpful (it should be YYYYMMDD).  It's 
> especially helpful when identifying exact branch and merge points - the 
> nature of cvs is such that "cvs log" is not exact.  Besides, there's 
> nothing to stop the person cutting the branch from using "cvs admin" to 
> create a shorter alias for the currently active longer tag.
> 
> Andrew

I'll say it again.  I really, *really*, hate dates in this context. 
I've found that when working with CVS on branches you have to use the
branch tag name with every update (or -dP doesn't work properly) and
since I'm not an historian I can never remember them!

If you really want some additional meta-info here, then require a
'project name'.  Then Redhat folks can name their projects based on the
date they started, if they so desire.  The rest of us can use more
memorable things, like 'gadfly' or 'wombat' or ...

Dates of branches should probably appear in the documentation for the
branch, but it doesn't IMO belong in the TAG name.

R.

Re: Branches in CVS repository?

[Andrew Cagney]

Richard Earnshaw wrote:
> On Wed, 2005-01-19 at 20:28, Andrew Cagney wrote:
> 
>>>Fair enough - if I am the only one who thinks that these dates would be 
>>>helpful then I am not going to insist on them.
>>
>>Yes, agreed, the date is very helpful (it should be YYYYMMDD).  It's 
>>especially helpful when identifying exact branch and merge points - the 
>>nature of cvs is such that "cvs log" is not exact. 
>>Andrew
> 
> 
> I'll say it again.  I really, *really*, hate dates in this context. 

to which I wrote:

 >> Besides, there's
 >>nothing to stop the person cutting the branch from using "cvs admin" to
 >>create a shorter alias for the currently active longer tag.

have a nice day,
Andrew

Re: Branches in CVS repository?

[Ian Lance Taylor]

Richard Earnshaw <rearnsha@gcc.gnu.org> writes:

> I'll say it again.  I really, *really*, hate dates in this context. 
> I've found that when working with CVS on branches you have to use the
> branch tag name with every update (or -dP doesn't work properly) and
> since I'm not an historian I can never remember them!

That bug was fixed a few years ago.  In current CVS update -d will
work correctly when you have a branch checked out.

Ian

Re: Branches in CVS repository?

[Thorsten Glaser]

Nick Clifton dixit:

>  * It documents when the branch was started without having to look in the
> logs.

It does not.

                       a                            b
mainline     []---------[]------------[]-------------[]--------------[]----...
                        \                             \
                         \                             \____
                          \                                 \
branch                     []----[]-----[]-------[]---------[]----[]----[]-...
                                                  c         d

You just merge to -rbranch the differences between a and b (-ja -jb)
when you're at c, thus creating d. Now d is obviously not based
upon mainline 'a' but mainline 'b'.

bye,
//mirabile (managing a cvs with about 97k files)

Re: Branches in CVS repository?

[Richard Earnshaw]

On Wed, 2005-01-19 at 05:51, Mark Mitchell wrote:
> Nick Clifton wrote:
> > Hi Guys,
> > 
> >>>> The informal GCC convention has been "<org>-<name>" where "org" is the 
> > 
> > 
> >>> RH's internal convention includes a YYMMDD somewhere, which is
> > 
> > 
> >> I'd meant to allow arbitrary characters in "name", which would 
> >> certainly permit what you suggest.
> > 
> > 
> > But it is best to be explicit.  How about:
> > 
> >   <module(s)>-<org>-<reason>-<date>
> > 
> > eg:
> > 
> >   binutils-csl-ARM_development-050118
> > 
> > which may be a little bit wordy, but should avoid all possibility if 
> > name space collisions and should make the purpose of the branch obvious.
> 
> I don't quite understand the date part.  Is this because we might merge 
> our changes forward to a new basepoint (like the 050221 mainline 
> version) later?  Our usual practice has been to merge the delta between 
> 050118 and 050221 onto our branch, rather than create a new branch.  May 
> we make the date optional?

I suspect it's a consequence of a couple of things.

1) CVS gets progressively less efficient the more revisions there are
between the head of the trunk and the head of your branch via the
branch-point.

2) For experimental branches, it's easier to walk away from them and cut
a new branch with a unique tag if it includes the date.

Personally, I find the use of dates awkward.  At any time after the
initial creation point the date is not much better than a random number,
and remembering what set of changes is associate with what date is
nigh-on impossible.

So I think that beyond the basic rules of <module>-<org> at the start of
tags (I'd add a class -- branchpoint, branch, release etc --  there as
well, but that's me) it really ought to be up to the owner of the
branch, since the prefix will always be sufficient to keep the tags from
interfering.

R.

Re: Branches in CVS repository?

[Nick Clifton]

Hi Guys,

 > Richard Earnshaw wrote:
> 
> Personally, I find the use of dates awkward.  At any time after the
> initial creation point the date is not much better than a random number,
> and remembering what set of changes is associate with what date is
> nigh-on impossible.

I actually find them useful.  Admittedly this is in the context of GCC, 
and RedHat supporting its customers, but if I see a branch that is say 
"CUSTOMER_FOO-gcc-990101" then I think "oh dear that is a very old 
branch, why haven't they upgraded ?", whereas if I see 
"CUSTOMER_BAR-gcc-050101" I think "hmm, they are using the latest 
sources and they still find bugs - this is going to be hard".  (Not that 
I am a pessimist or anything").

Cheers
   Nick

Re: Branches in CVS repository?

[DJ Delorie]

> All those directories and files are part of binutils.  Just because
> you add a branch tag does not mean that you necessarily modify those
> files.

True, but they pare part of other projects also.  Adding a branch
takes up space in the branch namespace of the other projects.  If you
create a "foo" branch in binutils, then you cannot create a "foo"
branch in gdb that reflects a different branch point.

Re: Branches in CVS repository?

[Andreas Schwab]

DJ Delorie <dj@redhat.com> writes:

> True, but they pare part of other projects also.  Adding a branch
> takes up space in the branch namespace of the other projects.  If you
> create a "foo" branch in binutils, then you cannot create a "foo"
> branch in gdb that reflects a different branch point.

That's true, but no sensible person would use such a tag name.

Andreas.

-- 
Andreas Schwab, SuSE Labs, schwab@suse.de
SuSE Linux Products GmbH, Maxfeldstraße 5, 90409 Nürnberg, Germany
Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: Branches in CVS repository?

[DJ Delorie]

> > True, but they pare part of other projects also.  Adding a branch
> > takes up space in the branch namespace of the other projects.  If you
> > create a "foo" branch in binutils, then you cannot create a "foo"
> > branch in gdb that reflects a different branch point.
> 
> That's true, but no sensible person would use such a tag name.

Sensible people would use, for example, "rh-mips-port" or "csl-arm" or
something similarly generic, and have the same problems.  The fact
that I have chosen a generic name "foo" doesn't mean I expect people
to use the actual name "foo" but serves as a placeholder for *any*
name which might cause such conflicts.

All I'm saying is that people who wish to be sensible need to
understand that whatever branch name they choose will cause a branch
to exist in ALL the src projects if they include common subdirectories
like libiberty.  They need to either plan to take advantage of this,
or plan to avoid the namespace collision issues.

RE: Branches in CVS repository?

[Dave Korn]

> -----Original Message-----
> From: binutils-owner On Behalf Of DJ Delorie
> Sent: 17 January 2005 17:50

> All I'm saying is that people who wish to be sensible need to
> understand that whatever branch name they choose will cause a branch
> to exist in ALL the src projects if they include common subdirectories
> like libiberty.  They need to either plan to take advantage of this,
> or plan to avoid the namespace collision issues.


  Specify that the branch tag must include the name of the project (or CVS
module, to be precise) for which the branch is intended.

<cvsmodule>-<org>-<name>

So you could have "binutils-dj-foo" and "gdb-dj-foo" and no conflict.


    cheers, 
      DaveK
-- 
Can't think of a witty .sigline today....

Re: Branches in CVS repository?

[Ben Elliston]

Nick Clifton <nickc@redhat.com> writes:

> I agree.  I can no reason to block this kind of behaviour and good
> reasons to encourage it.  So yes, I think that Mark should go ahead
> and create his branch.  In fact if he would like to propose a
> paragraph to be added to binutils/MAINTAINERS that we be welcome as
> well.

The GCC and NetBSD projects (two that I know with plenty of branching
activity) maintain a list of active branches.  I think it would make
sense to keep such a list for binutils -- most likely in the htdocs
directory.

Ben

Re: Branches in CVS repository?

[DJ Delorie]

> The GCC and NetBSD projects (two that I know with plenty of
> branching activity) maintain a list of active branches.  I think it
> would make sense to keep such a list for binutils -- most likely in
> the htdocs directory.

Whose htdocs?  Binutils, gdb, cygwin, newlib?

How about a file src/branches.txt that's part of the HEAD CVS checkout
for all projects (i.e. in modules) but not part of any of the "make
dist" scripts?

Re: Branches in CVS repository?

[Ben Elliston]

[-- Attachment #1: Type: text/plain, Size: 396 bytes --]

On Mon, Jan 17, 2005 at 09:21:41PM -0500, DJ Delorie wrote:

> How about a file src/branches.txt that's part of the HEAD CVS
> checkout for all projects (i.e. in modules) but not part of any of
> the "make dist" scripts?

That would be fine, too; how about following the convention of
MAINTAINERS and calling the file "BRANCHES"?  Then it will be
prominent at the top of directory listings.

Ben

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 189 bytes --]