Re: [Savannah-users] SVN Syntax Question

[Bob Proulx]

Hi Stephen,

Stephen H. Dawson wrote:
> Thanks for the reply. Some clarification and questions from your
> response to me.

Stephen and I had a private exchange and with permission I am moving
this part back to the mailing list.

> trunk directory:
> I believe I have miscomprehended the purpose of the trunk directory. I
> understood the purpose of the trunk directory is for a user to get the
> latest finished work. I now understand you telling me this is the
> directory of the latest development work. Am I correct in this new
> understanding?

First let me say that there is no single right answer.  Books have
been written about different ways of doing this.  Which makes it
harder in many ways.  Some people like things one way.  Some people
like things another way.

But there are conventions that make life easier for everyone.  One of
the expectations that I have is that if I find a project and check out
the trunk then I will get the latest development branch of the
project.  The trunk directory in subversion is just a name.  But it is
also by convention the main trunk of development.  Trunk as in the
tree analogy with everything starting at the root and splitting off
into branches from there.  The main trunk is the main part of the tree
of history.  It usually shows the entire history from start to finish
unless there are intentional disturbances along the way.

The workflow I prefer is that when a stable release branch is desired
that the release branch be created for the purpose of maintaining the
minor changes needed on that release.  If development has been
proceeding on the main trunk then copy the main trunk off creating a
release branch.  I usually only have the trunk or the branch checked
out at any one time.  Therefore, for me, I will need to use the URL of
the repository.  The URL can be seen using the svn info command.  I
will use "foo" as a placeholder for the real project name.

  svn info
  ...
  URL: svn+ssh://svn.savannah.gnu.org/foo/trunk
  ...

For the purpose of discussion I will store it away into a variable so
that I don't have to type so much.  I might do this on the command
line.  Or I might just cut-n-paste it in.  The long URL is a little
tedious.

  url=svn+ssh://svn.savannah.gnu.org/foo

I can now use "$url" for a shortcut.

  svn checkout $url/trunk foo
  cd foo

And I can then create a branch using the url to manipulate the
repository directly without regard to the local directory working
copy of checkout files.

  svn copy -m "Create stable release branch" $url/trunk $url/branches/foo-3.2

Having created it then I can switch my working copy over to it.  I
didn't check out everything, just the trunk.  So for me to work on it
I need to switch my local directory over to it.

  svn switch $url/branches/foo-3.2

You can use 'svn info' at any time to see what the local working copy
is attached to.  I do that often.  If I come back to a directory after
having been away I usually start by going 'svn info' to look so I will
know what state things are in.  And then almost always 'svn status'.

Now that I have switched onto the branch I can make changes there.  I
can make releases on that branch.  But hopefully only minor changes as
befitting a stable release branch.  No API changes.  Nothing like
that.  But small portability and bug fixes are perfect.

[[
  You might want to read this article.  This is again a religious
  topic.  Some people like it one way.  Others like it a different way.
  This matches with what I like and therefore I will reference it.

    Semantic Versioning
    http://semver.org/
]]

Back to the branch work in the working copy.  We switched to the
stable branch using the 'svn switch $url/branches/foo-3.2' command.
The working copy should always be clean.  Use 'svn status' to see.  We
can switch branches as needed.  We can switch back to the main trunk.

  svn switch $url/trunk

Or I often have two directories.

  mkdir $HOME/src/foo-stuff
  cd $HOME/src/foo-stuff
  svn checkout $url/trunk foo-trunk
  svn checkout $url/branches/stable-3.2 foo-stable-3.2

Instead of switching back and forth this way I can keep two
directories dedicated to each purpose.  It can be much less confusing
that way.

Always remember to update often!  Any change to any part of the
repository increments the top level version number.  That is the
"Revision:" field in the 'svn info' output.

  svn update

I did a lot of talking about creating a release branch above.  But
many projects keep things even simpler.  Many projects use a single
development trunk and release from it.  It is a best practice to
keep the main trunk always in a releasable state.  If it is always in
a releasable state then it is easy to make a release simply by tagging
it appropriately.  No need for any branches at all!

This is important so I will emphasize it.  If your main trunk is
always in a releasable state then it is easy to make releases.

> I understood the purpose of the trunk directory is for a user to get
> the latest finished work. I now understand you telling me this is
> the directory of the latest development work. Am I correct in this
> new understanding?

I repeated the above since I wrote so much already since then.  There
is no right answer.  Many people like different things.

But let me say this.  With software it is rarely a "finished work".
And therefore the main trunk goes on and on.

There is a maturity to it however.  Often software will need little
maintenance over decades.  That's okay.  Or it might have rapid
development all of the time.  And it may or may not have a stable
release.  As the maintainer you get to choose the course of
development you want to use to work with it.

I am not familiar specifically with remote control but it appears you
are making an archive of 1.1 and not expecting to make any more
changes to it.  That sounds perfect for tagging.  I don't think it
needs a branch.  I would simply tag it by making a copy of it to the
tags directory.  If there is need to revive it later then an active
branch could be made of it.  It will exist available for anyone to
checkout in the repository.

  svn copy -m "Tagging release 3.2" $url/trunk $url/tags/foo-3.2

If others on the mailing list would like to share their favorite
operating work flows with us that would be great.  I know I would be
interesting in the sharing of the ideas.

> [svn del trunk]:
> I am not clear. Would this syntax not kill all history of the trunk
> directory? If so, this is not good. If not, then I will use the syntax.

The history will always be there.  It is always available to browse.
For one it will always be associated with the new branch that was
created to host it.  After the copy to the branch you can view all of
the history as part of the branch.

  svn copy -m "Create stable release branch" $url/trunk $url/branches/foo-3.2
  svn switch $url/branches/foo-3.2
  svn log | less
    ...browse all of the history...

It looks to me that branches/Version2.0 has work toward your newest
main trunk development.  It has history that goes all of the way
back.  You mentioned wanting to make it be the main trunk.  That seems
reasonable at this point.  It has the history of everything that went
into that code base.  After moving it from the branch to the trunk it
will continue to have that history in the trunk.  My suggestion:

  svn update
  svn del trunk
  svn move branches/Version2.0 trunk
  svn commit -m "Moving branch to main trunk for continued
  development."

The "svn del trunk" looks scary but it can't actually delete svn
history (more on that in a moment) and this is just to prepare the way
to move "branches/Version2.0" over to "trunk".

[[
  Subversion never actually deletes history.  Even if everything were
  deleted (please don't though) it all would still be in the history.
  It is just more difficult to browse.  If everything were deleted
  then to access it one needs to specify the subversion syntax of a
  version number when the files did exist.  By specifying a "revision
  specifier" you can check out the previous version which had the
  files that were later removed and see them.  That svn docs describe
  this in detail so I don't want to here.  Just let me say that it is
  easily gotten to even if it has been removed from the current
  version.
]]

> [svn move]
> I do not want to move. I want to have a static copy of the release until
> we get a better handle on SVN work as project team.

A static copy sounds like a tagged copy to me.  Tags should be created
exactly once and then never changed again afterward.  This sounds
perfect for tagging.

If you write a little description of what you are wanting to
accomplish with enough background for us to understand what the goals
are then we on the mailing list could suggest things to do.  I think I
know what you want but I am not sure.  And here it appears I don't
quite understand yet.

> Release Announcement SVN Path:
> I am fine with announcing the path to the latest and greatest release is
> in the branch section. What svn syntax should I provide in the
> announcement of the newest version?
>
> svn://svn.sv.gnu.org/remotecontrol/branches/Version2.0/
>
> Is this correct?

If you want to the world to checkout a branch that is okay.  I suggest
this syntax in that case.

  svn checkout svn://svn.sv.gnu.org/remotecontrol/branches/Version2.0 
remotecontrol-2.0

> Tags:
> Yes, we need to use tags. We as a team are not to the point of
> accomplishing this level of repository management. I hope we will be
> there soon.

Tags are very lightweight.  They are easy to create.

  svn copy -m "Tagging release 3.2" $url/trunk $url/tags/foo-3.2

Every release should be tagged for future reference.  This can be done
at any time the release version is finalized.  Today.  Next week.
Next month.  It's never too late.

It can be too early however.  Tagging a "candidate" as a release
before it has actually released is basically the same as releasing it
in my strict view of the world.  Because even though subversion allows
you to remove and recreate the tag on a later version that creates an
ambiguity.  Did someone pull the first release of 3.2 or the 3rd
release of 3.2?  Shudder!  I once saw a project make *FOUR* releases
of exactly the same version number.  That's bad.  If this happens to
you don't try to salvage a number.  There are lots of numbers.  We
aren't going to run out.  Simply move on to the next number and do not
worry about it further.

Additionally I don't like projects that release purely from a version
tracker.  I am old school and like to see an actual release bundle of
files that can be put onto the mirror site and propagated.  Because
not everyone has a live network connection.  Even if most of the users
do there will be many that do not.  Philosophically I want to make
free libre software available to everyone that wishes to use it.  Even
if they are on a space station or at a research hut in Antartica or a
small village in the developing world.  High bandwidth networking is
not universial.  Making release bundles makes the software available
to everyone and I think is a very important part of project
maintenance.

Whew!  Sorry for writing a novel.  Hope this discussion helps!  I also
welcome constructive discussion about this from other members of the
mailing list.

Bob