You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@subversion.apache.org by Pavel Lyalyakin <pa...@visualsvn.com> on 2017/09/22 16:57:02 UTC
[PATCH] Let's rework the Quick Start page (publish/quick-start.html)
Hello,
It appears that the current SVN Quick Start page[1] is kind of desolate; there
is a discussion about updating it[2]. I want to volunteer for this task and I am
attaching a patch. :)
My idea is to provide novice SVN end users with a quick reference on the most
basic concepts and operations:
* checkout a working copy,
* update the working copy,
* modify the data in the working copy and commit it,
* make a branch or tag.
A user who needs help on how to begin working with SVN does not have to dive
into the SVNBook. Yes, he will read the SVNBook some time later to learn more
about basic operations and to find out about the magic of the complex ones. But
not on his first day when the only commands he needs are `svn checkout` and
`svn commit`.
Log Message:
[[[
* publish/quick-start.html:
Reworking the SVN Quick Start page as discussed in
https://lists.apache.org/thread.html/da5b9f351a1bf2456aeb85e24ed88ff30b544a70995638af684684f1@%3Cdev.subversion.apache.org%3E
]]]
[1]: https://subversion.apache.org/quick-start
[2]: https://lists.apache.org/thread.html/da5b9f351a1bf2456aeb85e24ed88ff30b544a70995638af684684f1@%3Cdev.subversion.apache.org%3E
Re: [PATCH] Let's rework the Quick Start page (publish/quick-start.html)
Posted by Pavel Lyalyakin <pa...@visualsvn.com>.
Hello Johan,
On Tue, Oct 3, 2017 at 1:58 PM, Johan Corveleyn <jc...@gmail.com> wrote:
>
> On Tue, Oct 3, 2017 at 11:37 AM, Daniel Shahaf <d....@daniel.shahaf.name> wrote:
> > Pavel Lyalyakin wrote on Mon, 02 Oct 2017 13:41 +0300:
> >> I am going to work on further improvements and as soon as they are ready, I will
> >> start a new [PATCH] thread. However, what about creating a lightweight branch[1]
> >> for this doc task? I know that a lightweight branch can be created for code
> >> changes, but the site/ does not have branches at all. I am not sure about that.
> >
> > We can certainly create branches of the site. E.g., we could copy site/publish/
> > to site/staging/ and even have it served as http://subversion.staging.apache.org/
> > for ease of previewing.
> >
> > I'll let Johan respond to the other parts of your question :-).
>
> Hi Pavel,
>
> I've commit your v3 patch in r1810571 (I just did a small tweak to the
> commit message: "Reworking" -> "Rework", i.e. we prefer to use
> imperative in log messages when describing what you've done).
>
> I agree it would be easier if you could commit directly (either to
> some "staging" branch, or to the site directly). I'm working on making
> that happen, stay tuned ... :-).
It would be great. Thank you. :)
> --
> Johan
--
With best regards,
Pavel Lyalyakin
VisualSVN Team
Re: [PATCH] Let's rework the Quick Start page (publish/quick-start.html)
Posted by Johan Corveleyn <jc...@gmail.com>.
On Tue, Oct 3, 2017 at 11:37 AM, Daniel Shahaf <d....@daniel.shahaf.name> wrote:
> Pavel Lyalyakin wrote on Mon, 02 Oct 2017 13:41 +0300:
>> I am going to work on further improvements and as soon as they are ready, I will
>> start a new [PATCH] thread. However, what about creating a lightweight branch[1]
>> for this doc task? I know that a lightweight branch can be created for code
>> changes, but the site/ does not have branches at all. I am not sure about that.
>
> We can certainly create branches of the site. E.g., we could copy site/publish/
> to site/staging/ and even have it served as http://subversion.staging.apache.org/
> for ease of previewing.
>
> I'll let Johan respond to the other parts of your question :-).
Hi Pavel,
I've commit your v3 patch in r1810571 (I just did a small tweak to the
commit message: "Reworking" -> "Rework", i.e. we prefer to use
imperative in log messages when describing what you've done).
I agree it would be easier if you could commit directly (either to
some "staging" branch, or to the site directly). I'm working on making
that happen, stay tuned ... :-).
--
Johan
Re: [PATCH] Let's rework the Quick Start page (publish/quick-start.html)
Posted by Daniel Shahaf <d....@daniel.shahaf.name>.
Pavel Lyalyakin wrote on Mon, 02 Oct 2017 13:41 +0300:
> I am going to work on further improvements and as soon as they are ready, I will
> start a new [PATCH] thread. However, what about creating a lightweight branch[1]
> for this doc task? I know that a lightweight branch can be created for code
> changes, but the site/ does not have branches at all. I am not sure about that.
We can certainly create branches of the site. E.g., we could copy site/publish/
to site/staging/ and even have it served as http://subversion.staging.apache.org/
for ease of previewing.
I'll let Johan respond to the other parts of your question :-).
Cheers,
Daniel
Re: [PATCH] Let's rework the Quick Start page (publish/quick-start.html)
Posted by Pavel Lyalyakin <pa...@visualsvn.com>.
Hello,
On Sat, Sep 30, 2017 at 1:41 AM, Johan Corveleyn <jc...@gmail.com> wrote:
> On Wed, Sep 27, 2017 at 5:08 PM, Pavel Lyalyakin
> <pa...@visualsvn.com> wrote:
>> Hello Johan,
>>
>> Thank you for taking the time to review this patch. :)
>>
>> I think that I addressed most of your comments and suggestions in the
>> attached patch svn-updated-quick-start-v3.patch.txt. I've attached an
>> interdiff to v2 patch, too.
>
> That's all looking great, Pavel, nice work.
Thanks for the review. :)
> [snip]
>
>> Sure, I am going to continue with this task. The current version of
>> the document (as it is in v3 patch) is missing several important
>> sections that I thing about adding:
>> * Viewing the history of changes: provide `svn log` examples.
>> * Merging: automatic reintegration merges and cherry-picking.
>> * Tagging: we should provide tagging examples.
>> * Creating your own local repository: a quick guide on this task with
>> a link to SVNBook's High-Speed Tutorial.
>
> I'd like to commit your current v3 patch, so we already have this in
> place. Further improvements can then happen in followup patches /
> commits. Unless you prefer to make it more complete before committing
> anything? I don't see a reason myself to hold back and make
> incremental improvements later, but I'll wait for you to let me know
> what you prefer.
Sure, please, commit v3 patch. It will help me divide further work into atomic
patches or commits instead of a single blanket patch. I'm sure that it will be
much easier to review the document this way.
I am going to work on further improvements and as soon as they are ready, I will
start a new [PATCH] thread. However, what about creating a lightweight branch[1]
for this doc task? I know that a lightweight branch can be created for code
changes, but the site/ does not have branches at all. I am not sure about that.
[1]: http://subversion.apache.org/docs/community-guide/general.html#lightweight-branches
--
With best regards,
Pavel Lyalyakin
VisualSVN Team
Re: [PATCH] Let's rework the Quick Start page (publish/quick-start.html)
Posted by Johan Corveleyn <jc...@gmail.com>.
On Wed, Sep 27, 2017 at 5:08 PM, Pavel Lyalyakin
<pa...@visualsvn.com> wrote:
> Hello Johan,
>
> Thank you for taking the time to review this patch. :)
>
> I think that I addressed most of your comments and suggestions in the
> attached patch svn-updated-quick-start-v3.patch.txt. I've attached an
> interdiff to v2 patch, too.
That's all looking great, Pavel, nice work.
[snip]
> Sure, I am going to continue with this task. The current version of
> the document (as it is in v3 patch) is missing several important
> sections that I thing about adding:
> * Viewing the history of changes: provide `svn log` examples.
> * Merging: automatic reintegration merges and cherry-picking.
> * Tagging: we should provide tagging examples.
> * Creating your own local repository: a quick guide on this task with
> a link to SVNBook's High-Speed Tutorial.
I'd like to commit your current v3 patch, so we already have this in
place. Further improvements can then happen in followup patches /
commits. Unless you prefer to make it more complete before committing
anything? I don't see a reason myself to hold back and make
incremental improvements later, but I'll wait for you to let me know
what you prefer.
--
Johan
Re: [PATCH] Let's rework the Quick Start page (publish/quick-start.html)
Posted by Pavel Lyalyakin <pa...@visualsvn.com>.
Hello Johan,
Thank you for taking the time to review this patch. :)
I think that I addressed most of your comments and suggestions in the
attached patch svn-updated-quick-start-v3.patch.txt. I've attached an
interdiff to v2 patch, too.
Here is a modified log message.
Log Message:
[[[
* publish/quick-start.html:
Reworking the SVN Quick Start page as discussed on dev@s.a.o [1]
[1] https://lists.apache.org/thread.html/da5b9f351a1bf2456aeb85e24ed88ff30b544a70995638af684684f1@%3Cdev.subversion.apache.org%3E
Patch by: Pavel Lyalyakin <pavel.lyalyakin[_at_]visualsvn.com>
]]]
On Tue, Sep 26, 2017 at 3:05 AM, Johan Corveleyn <jc...@gmail.com> wrote:
>
> On Fri, Sep 22, 2017 at 6:57 PM, Pavel Lyalyakin
> <pa...@visualsvn.com> wrote:
> > Hello,
> >
> > It appears that the current SVN Quick Start page[1] is kind of desolate; there
> > is a discussion about updating it[2]. I want to volunteer for this task and I am
> > attaching a patch. :)
> >
> > My idea is to provide novice SVN end users with a quick reference on the most
> > basic concepts and operations:
> > * checkout a working copy,
> > * update the working copy,
> > * modify the data in the working copy and commit it,
> > * make a branch or tag.
> >
> > A user who needs help on how to begin working with SVN does not have to dive
> > into the SVNBook. Yes, he will read the SVNBook some time later to learn more
> > about basic operations and to find out about the magic of the complex ones. But
> > not on his first day when the only commands he needs are `svn checkout` and
> > `svn commit`.
> >
> > Log Message:
> > [[[
> > * publish/quick-start.html:
> > Reworking the SVN Quick Start page as discussed in
> > https://lists.apache.org/thread.html/da5b9f351a1bf2456aeb85e24ed88ff30b544a70995638af684684f1@%3Cdev.subversion.apache.org%3E
> > ]]]
> >
> > [1]: https://subversion.apache.org/quick-start
> > [2]: https://lists.apache.org/thread.html/da5b9f351a1bf2456aeb85e24ed88ff30b544a70995638af684684f1@%3Cdev.subversion.apache.org%3E
>
> Hi Pavel,
>
> Thanks again for taking this on. I'll try to give some feedback below.
>
>
> > Index: publish/quick-start.html
> > ===================================================================
> > --- publish/quick-start.html (revision 1808237)
> > +++ publish/quick-start.html (working copy)
> > @@ -17,62 +17,433 @@
> >
> > <h1>Apache Subversion: Quick Start</h1>
> >
> > -<div class="h2" id="gui">
> > -<h2>Graphical user interface (GUI) clients
> > - <a class="sectionlink" href="#gui"
> > - title="Link to this section">¶</a>
> > -</h2>
> > +<ul>
> > + <li>
> > + <a href="#installing-the-client">Installing the SVN client</a>
> > + </li>
> > + <li>
> > + <a href="#understanding-the-terms">Understanding the terms</a>
>
> I think "terms" can have the meaning of "terms of the agreement", or
> "terms of the license". I think "terminology" is better. Maybe just
> call this section "Terminology" (without the "understanding the ...").
I like "Terminology" without "Understanding ...". Fixed in v3 patch.
> > + </li>
> > + <li>
> > + <a href="#basic-tasks">Basic tasks</a>
> > + </li>
> > + <li>
> > + <a href="#branching-and-tagging">Branching and tagging</a>
> > + </li>
> > + <li>
> > + <a href="#more-help">Getting more help</a>
> > + </li>
> > +</ul>
> >
> > -<p>If you are not familiar with Subversion, you may be better served by a
> > -graphical client. (The Subversion project only maintains a command-line-based
> > -clients, but a number of third parties maintain graphical clients that build on
> > -<a href="/docsapi/latest/">our API (for programmers)</a>.) We do not maintain
> > -a list of such clients; instead, we recommend you do a Web search for
> > -<tt>Subversion GUI client</tt>.
> > -
> > -</div>
> > -
> > -<div class="h2" id="bootstrap">
> > -<h2>Make an existing directory a working copy of a new repository
> > - <a class="sectionlink" href="#bootstrap"
> > - title="Link to this section">¶</a>
> > -</h2>
> > -
> > -<p>The following commands will convert a <tt>./my-directory/</tt> containing
> > -files into a working copy of a newly-created repository:</p>
> > -
> > -<p>On Unix:</p>
> > -
> > + <div class="h2" id="installing-the-client">
> > + <h2>
> > + Installing the SVN client
> > + <a class="sectionlink" href="#installing-the-client"
> > + title="Link to this section">¶</a>
> > + </h2>
> > + <p>
> > + Install the <tt>svn</tt> client to start collaborating on the project
>
> "the project" -> "a project"
Fixed in v3 patch.
> > + that is using Subversion as its version control system.
> > + </p>
> > + <p>
> > + To install the client program, you can build it yourself from a source
> > + code release or download a binary package. The list of sites where you
> > + can obtain a pre-built Subversion client is available at the
> > + <a href="/packages.html">official binary packages page</a>. If you want
> > + to compile the software for yourself, grab the source at the
> > + <a href="/source-code.html">Source Code</a> page.
> > + </p>
> > + <p>
> > + Right after you install the client you should be able to test it by
> > + issuing the svn command. You should see the following output:
> > + </p>
> > <pre>
> > -$ mkdir -p $HOME/.svnrepos/
> > -$ svnadmin create ~/.svnrepos/my-repos
> > -$ svn mkdir -m "Create directory structure."
> > file://$HOME/.svnrepos/my-repos/trunk
> > file://$HOME/.svnrepos/my-repos/branches
> > file://$HOME/.svnrepos/my-repos/tags
> > -$ cd my-directory
> > -$ svn checkout file://$HOME/.svnrepos/my-repos/trunk ./
> > -$ svn add --force ./
> > -$ svn commit -m "Initial import"
> > -$ svn up
> > +$ svn
> > +Type 'svn help' for usage.
> > </pre>
> > + <p>
> > + Now you can start using the command line client to interact with the
> > + remote repository.
> > + </p>
> > + <div class="notice">
> > + <p>
> > + If you are not familiar with Subversion, you may be better served by a
> > + graphical client. We do not maintain a list of such clients; instead,
> > + we recommend you do a Web search for <tt>Subversion GUI</tt> client.
> > + </p>
> > + </div>
> > + </div>
> >
> > -<p>On Windows:</p>
> > + <div class="h2" id="understanding-the-terms">
> > + <h2>
> > + Understanding the terms
> > + <a class="sectionlink" href="#understanding-the-terms"
> > + title="Link to this section">¶</a>
> > + </h2>
>
> So let's say "Terminology" here.
Fixed in v3 patch.
> > + <div class="h3" id="what-is-a-repository">
> > + <h3>
> > + What is a Repository?
> > + <a class="sectionlink" href="#what-is-a-repository"
> > + title="Link to this section">¶</a>
> > + </h3>
> > + <p>
> > + The repository is a version control database that often resides on a
> > + server and is usually exposed either by Apache HTTP Server
> > + (mod_dav_svn) or svnserve server.
>
> I'd say "by *an* Apache HTTP Server (*through the mod_dav_svn module*)
> or *by an* svnserve server".
Fixed in v3 patch.
> > The repository acts as a single
> > + source of truth and – as a central storage – it contains the complete
> > + history of changes of the versioned data in form of revisions.
> > + </p>
> > + <p>
> > + Repository URL examples:
> > + </p>
> > + <ul>
> > + <li>
> > + Apache HTTP Server:
> > <tt>https://svn.example.com/repos/MyRepo/MyProject/trunk</tt>
> > + </li>
> > + <li>
> > + svnserve: <tt>svn://svn.example.com/repos/MyRepo/MyProject/trunk</tt>
> > + </li>
> > + <li>
> > + Direct access (Unix-style):
> > <tt>file://var/svn/repos/MyRepo/MyProject/trunk</tt>
> > + </li>
> > + <li>
> > + Direct access (Windows-style):
> > <tt>file:///C:/Repositories/MyRepo/MyProject/trunk</tt>
> > + </li>
> > + </ul>
>
> Maybe not all of these examples should have the "MyProject/trunk",
> because there is a lot of diversity out there. Maybe throw a
> "/trunk/MyProject" in there, and a "/branches/mybranch" or
> "/tags/1.1.0"?
Yes, let's provide different URL examples. Fixed in v3 patch.
> > + </div>
> > + <div class="h3" id="what-is-a-working-copy">
> > + <h3>
> > + What is a Working Copy?
> > + <a class="sectionlink" href="#what-is-a-working-copy"
> > + title="Link to this section">¶</a>
> > + </h3>
> > + <p>
> > + The working copy is your local and private workspace that you use to
> > + interact with the central Subversion repository. You use the working
> > + copy to modify the contents of your project and fetch changes committed
> > + by others.
> > + </p>
> > + <p>
> > + The working copy contains your project's data and looks and acts like a
> > + regular directory on your local file system, but with one major
> > + difference - the working copy tracks the status and changes of files
> > + and directories within. You can think of the working copy as of a
> > + regular directory with version-control capabilities.
> > + </p>
>
> Maybe add a sentence to explain that Subversion keeps metadata in a
> .svn directory in the root of the working copy, to manage those
> version-control capabilities. (in case people start wondering how it
> works, and how it's physically different from a regular directory).
Yes, I agree that it makes sense to mention ".svn" directory here.
Fixed in v3 patch.
[[[
A working copy has an administrative directory named <tt>.svn</tt> at
its root. The administrative directory contains metadata necessary for
Subversion to manage the version-control capabilities.
]]]
> > + <p>
> > + There can be as much working copies from the same repository or project
> > + as you want with any combination of local modifications.
> > + </p>
> > + </div>
> > + </div>
> >
> > + <div class="h2" id="basic-tasks">
> > + <h2>
> > + Basic tasks
> > + <a class="sectionlink" href="#basic-tasks"
> > + title="Link to this section">¶</a>
> > + </h2>
> > + <div class="h3" id="importing-data">
> > + <h3>
> > + Importing data into the repository
> > + <a class="sectionlink" href="#importing-data"
> > + title="Link to this section">¶</a>
> > + </h3>
> > + <p>
> > + In case you want to import an existing non-versioned data to SVN
>
> Grammar tweak: drop the "an" before "existing", and add "an" before
> SVN (and I'd say "*into* an SVN repository").
Fixed in v3 patch.
> > + repository, you should run the
> > + <a href="http://svnbook.red-bean.com/en/1.8/svn.ref.svn.c.import.html">
> > + <tt>svn import</tt></a> command. Here is an example:
> > + </p>
> > <pre>
> > -> mkdir C:\repos
> > -> svnadmin create C:\repos\my-repos
> > -> svn mkdir -m "Create directory structure."
> > "file:///C:/repos/my-repos/trunk" "file:///C:/repos/my-repos/branches"
> > "file:///C:/repos/my-repos/tags"
> > -> cd my-directory
> > -> svn checkout "file:///C:/repos/my-repos/trunk" ./
> > -> svn add --force ./
> > -> svn commit -m "Initial import"
> > -> svn up
> > +$ svn import https://svn.example.com/repos/MyRepo/MyProject/trunk -m
> > "Initial project import"
> > </pre>
> > -
> > -<p>See also <a
> > -href="http://svnbook.red-bean.com/nightly/en/svn.intro.quickstart.html"
> > ->quickstart instructions in The Subversion Book</a>.</p>
> > -
> > -</div> <!-- bootstrap -->
> > -
> > -</div> <!-- #site-content -->
> > + </div>
> > + <div class="h3" id="checking-out-a-working-copy">
> > + <h3>
> > + Checking out a working copy
> > + <a class="sectionlink" href="#checking-out-a-working-copy"
> > + title="Link to this section">¶</a>
> > + </h3>
> > + <p>
> > + To begin making modifications to your project's data, you have to
> > + create a local copy of the versioned project. You can use the command
> > + line <tt>svn</tt> client or any GUI-based client that you prefer. Your
> > + local copy of the project is called a working copy and
> > + you create it by issuing the
> > + <a href="http://svnbook.red-bean.com/en/1.8/svn.ref.svn.c.checkout.html">
> > + <tt>svn checkout</tt></a> command. Here is an example:
> > + </p>
> > +<pre>
> > +$ svn checkout https://svn.example.com/repos/MyRepo/MyProject/trunk
> > +</pre>
> > + <p>
> > + As a result, you will get a working copy of the trunk of a project
> > + called MyProject that resides in MyRepo repository. The working copy
> > + will be located in MyProject directory on your computer. Note that
>
> I think it will be located in a "trunk" directory on your computer.
> Unless you do:
> svn checkout https://svn.example.com/repos/MyRepo/MyProject/trunk MyProject
Yes, the command was missing MyProject path.
> Though that might be a bit confusing, people might think the
> "MyProject" argument is somehow special, while it's just the target
> directory. Maybe something like "MyWork"? Or just say here that it'll
> be located in a directory "trunk" (last path component as default
> target dir)?
What about "MyWorkingCopy"? It should make it clearer I think.
[[[
svn checkout https://svn.example.com/repos/MyRepo/MyProject/trunk MyWorkingCopy
]]]
Fixed in v3 patch.
> > + instead of checking out the trunk, you can check out some branch
> > + or a tag (assuming they already exist in the repository).
> > + </p>
> > + <p>
> > + You can get the working copy of the whole repository MyRepo, too. But
> > + you should refrain from doing so. Generally speaking, you do not need
> > + to have a working copy of the whole repository for your work because
> > + your working copy can be instantly switched to another development
> > + branch. Moreover, Subversion repository can contain a number of
> > + unrelated projects and it is better to have a dedicated working copy
> > + for each of them, not a single working copy for all of the projects.
>
> Not to mention the repository database stores all different variations
> of the code (branches, tags) in an efficient way. It's usually not a
> good idea to check out all branches and tags onto a local disk as real
> directories. Dunno if we should mention that here though ...
I would skip that for now.
> > + </p>
> > + </div>
> > + <div class="h3" id="updating-a-working-copy">
> > + <h3>
> > + Updating a working copy
> > + <a class="sectionlink" href="#updating-a-working-copy"
> > + title="Link to this section">¶</a>
> > + </h3>
> > + <p>
> > + You are not the only person working on the project, right? This means
> > + that your colleagues are also making modifications to the project's
> > + data. To stay up to date and to fetch the modifications committed by
> > + others, you should run the
> > + <a href="http://svnbook.red-bean.com/en/1.8/svn.ref.svn.c.update.html">
> > + <tt>svn update</tt></a> command in your working copy. As a result,
> > + your working copy will sync with the repository and download the
> > + changes made by your colleagues.
> > + </p>
> > + <p>
> > + It is a rule to update your working copy before committing local
> > + modifications to the repository.
>
> No, I wouldn't say that. Maybe you could say that's "good practice" (I
> think in general it is, though it depends I guess).
Fixed in v3 patch. We may also use "common practice" instead of "good practice".
> > + </p>
> > + </div>
> > + <div class="h3" id="making-changes">
> > + <h3>
> > + Making changes in your local working copy
> > + <a class="sectionlink" href="#making-changes"
> > + title="Link to this section">¶</a>
> > + </h3>
> > + <p>
> > + Most of the time, you are going to perform modifications to the
> > + project's data by modifying the contents of the working copy. As soon
> > + as you are satisfied with the modifications and you've reviewed them
> > + thoroughly, you are ready to publish them to the central repository.
>
> Maybe you can already mention the word "commit" in that sentence?
> Perhaps just say: "..., you are ready to commit them to the central
> repository."
Yes, let's change "publish" to "commit" here. Fixed in v3 patch.
> > + </p>
> > + <div class="h4" id="modifying-existing-files">
> > + <h4>
> > + Modifying existing files
> > + <a class="sectionlink" href="#modifying-existing-files"
> > + title="Link to this section">¶</a>
> > + </h4>
> > + <p>
> > + Modify the files as you usually do using your favorite text
> > + processor, graphics editor, audio editing software, IDE, etc. As
> > + soon as you save the changes to disk, Subversion will recognize them
> > + automatically.
> > + </div>
> > + <div class="h4" id="committing-changes">
> > + <h4>
> > + Committing your changes to the repository
> > + <a class="sectionlink" href="#committing-changes"
> > + title="Link to this section">¶</a>
> > + </h4>
> > + <p>
> > + In order to publish the changes you made in your working copy, you
> > + should run the
> > + <a href="http://svnbook.red-bean.com/en/1.8/svn.ref.svn.c.commit.html">
> > + <tt>svn commit</tt></a> command.
> > + </p>
> > + <div class="notice">
> > + <p>
> > + Review your changes before committing them! Use the
> > + <a
> > href="http://svnbook.red-bean.com/en/1.8/svn.ref.svn.c.status.html">
> > + <tt>svn status</tt></a> and
> > + <a
> > href="http://svnbook.red-bean.com/en/1.8/svn.ref.svn.c.diff.html">
> > + <tt>svn diff</tt></a> commands to review the changes.
> > + </p>
> > + </div>
> > + <p>
> > + Here is an example of the commit command:
> > + </p>
> > +<pre>
> > +$ svn commit -m "My Descriptive Log Message"
> > +</pre>
> > + <p>
> > + Note the <tt>-m (--message)</tt> option. You must always include
> > + descriptive commit log message. The log message has to help others
> > + to understand why you made this commit, it has to contain a summary
> > + of the changes you made.
>
> The imperatives are a bit strong here. Perhaps rephrase it to: "You
> should always include a descriptive commit log message. It should help
> others (including your future self) understand why you made this
> commit. Apart from the "why" it's a good idea to include a summary of
> your changes in the log message."
>
> Or something like that.
Fixed in v3 patch.
> > + </p>
> > + </div>
> > + </div>
> > + <div class="h3" id="performing-file-operations">
> > + <h3>
> > + Performing file operations
> > + <a class="sectionlink" href="#performing-file-operations"
> > + title="Link to this section">¶</a>
> > + </h3>
>
> Hmmm, this is not only about files, is it? Maybe you should name this
> section "Performing tree changes", or "Performing file and directory
> operations".
"Performing file and directory operations" sounds better IMO. Fixed in v3 patch.
> > + <p>
> > + You can perform any actions with your project's data within the working
> > + copy, but operations that involve copying, moving, renaming and
> > + deleting must be performed using the corresponding <tt>svn</tt>
> > + commands.
> > + </p>
> > + <div class="h4" id="adding-new-files">
> > + <h4>
> > + Adding new files
> > + <a class="sectionlink" href="#adding-new-files"
> > + title="Link to this section">¶</a>
> > + </h4>
> > + <p>
> > + Put new files to the working copy and Subversion will recognize them
> > + as unversioned. It will not automatically start tracking the new
> > + files unless you run the
> > + <a href="http://svnbook.red-bean.com/en/1.8/svn.ref.svn.c.add.html">
> > + <tt>svn add</tt></a> command:
>
> I think you can replace "files" with "files and directories" in the
> above paragraph and title to make it a bit more general.
>
> Also, I think "recognize them as unversioned" is a bit confusing (the
> word "recognize" gives the impression that Subversion handles them
> somehow). Maybe "Subversion will *see* them as 'unversioned'" (quoting
> the word unversioned to point out it's a defined term).
Fixed in v3 patch.
> > + </p>
> > +<pre>
> > +$ svn add foo.cs
> > +</pre>
> > + </div>
> > + <div class="h4" id="moving-and-renaming-files-and-directories">
> > + <h4>
> > + Moving and renaming files and directories
> > + <a class="sectionlink"
> > href="#moving-and-renaming-files-and-directories"
> > + title="Link to this section">¶</a>
> > + </h4>
> > + <p>
> > + Move and rename files and directories using the
> > + <a href="http://svnbook.red-bean.com/en/1.8/svn.ref.svn.c.move.html">
> > + <tt>svn move</tt></a> or <tt>svn rename</tt> command:
> > + </p>
> > +<pre>
> > +$ svn move foo.cs bar.cs
> > +</pre>
> > + <p>
> > + The command <tt>svn rename</tt> is an alias for the
> > + <tt>svn move</tt>.
> > + </p>
>
> Maybe a small word of warning should be put here: if you move a file
> or directory with regular filesystem commands, Subversion will not
> know about the move, and will just see an unrelated add and delete. To
> get good results Subversion should be made aware of moves, so it can
> track them in its metadata (this is a definite difference from the
> heuristic-tracking DVCS'es ... Subversion requires explicit tracking
> of tree changes).
Let's put this under (#performing-file-and-dir-operations) /
(#performing-file-operations) secition. This note applies to all tree
changes and I don't think that we should repeat this information in
every child section.
> > + </div>
> > + <div class="h4" id="copying-files-and-directories">
> > + <h4>
> > + Copying files and directories
> > + <a class="sectionlink" href="#copying-files-and-directories"
> > + title="Link to this section">¶</a>
> > + </h4>
> > + <p>
> > + Copy files and directories using the
> > + <a href="http://svnbook.red-bean.com/en/1.8/svn.ref.svn.c.copy.html">
> > + <tt>svn copy</tt></a> command:
> > + </p>
> > +<pre>
> > +$ svn copy foo.cs bar.cs
> > +</pre>
>
> The above is a bit tricky, as 'svn copy' also creates a branch of the
> copied item, and the line of history is split (or put another way: the
> copied item is linked to the same pre-copy history). It's a bit
> difficult to explain all this in a quick start guide, unless you have
> some ideas.
>
> Maybe it's good as it is, but OTOH I've seen that often users are
> surprised by this (and really just wanted to copy the file contents,
> but not make it historically related to the original file).
>
> Maybe we should just drop this section "copying files and directories"
> for now? ('svn copy' is also mentioned later on in the "branching"
> section)
I'm not sure about that. I think that it is good to mention `svn copy`
command here and not mention pre-copy history link. If a user makes a
copy with regular `cp` command, he will get an unversioned file or
directory in his working copy and this may be an issue.
> > + </div>
> > + <div class="h4" id="deleting-files-and-directories">
> > + <h4>
> > + Deleting files and directories
> > + <a class="sectionlink" href="#deleting-files-and-directories"
> > + title="Link to this section">¶</a>
> > + </h4>
> > + <p>
> > + Delete files and directories using the svn delete
> > + <a href="http://svnbook.red-bean.com/en/1.8/svn.ref.svn.c.delete.html">
> > + <tt>svn delete</tt></a> command:
> > + </p>
> > +<pre>
> > +$ svn delete foo.cs
> > +</pre>
>
> Maybe here too, a small warning that if you delete files or
> directories with regular filesystem commands, Subversion will not know
> about the delete. It will regard the item as "missing" (having
> metadata but no corresponding file), and will bring it back on the
> next 'svn update'.
>
> > + </div>
> > + <div class="h4" id="reverting-local-changes">
> > + <h4>
> > + Reverting or discarding local changes
> > + <a class="sectionlink" href="#reverting-local-changes"
> > + title="Link to this section">¶</a>
> > + </h4>
> > + <p>
> > + Revert your local uncommitted changes using the
>
> ^^ Maybe say "Discard your local ...", so it's immediately clear what
> 'svn revert' does.
Fixed in v3 patch.
> > + <a href="http://svnbook.red-bean.com/en/1.8/svn.ref.svn.c.revert.html">
> > + <tt>svn revert</tt></a> command:
> > + </p>
> > +<pre>
> > +$ svn revert foo.cs
> > +</pre>
> > + <div class="notice">
> > + <p>
> > + Discarded uncommitted changes will be lost forever. You
> > will not be
> > + able to recover the reverted changes. Use <tt>svn revert</tt> with
> > + caution!
> > + </p>
> > + </div>
> > + </div>
> > + </div>
> > + <div class="h3" id="branching-and-tagging">
> > + <h3>
> > + Branching and tagging
> > + <a class="sectionlink" href="#branching-and-tagging"
> > + title="Link to this section">¶</a>
> > + </h3>
> > + <p>
> > + You should use the <tt>svn copy</tt> command to create branches and
> > + tags. This is the same command that is used to copy items in your
> > + working copy and in the repository.
>
> ... if you want them to be historically related (?)
Yes, let's add this. Fixed in v3 patch.
> > + </p>
> > + <p>
> > + The command <tt>svn copy</tt> is used for branching because, branch is
> > + technically a copy of the source you copy from. However, this is not
> > + an ordinary copy are familiar with when copying files on your local
> > + file system.
>
> There's a word missing in the above sentence.
Oops, my bad. Fixed in v3 patch.
> > Branches in Subversion are so called
> > + <a href="http://svnbook.red-bean.com/en/1.8/svn.branchmerge.using.html#svn.branchmerge.using.create">
> > + "Cheap Copies"</a> that are similar to symlinks.
>
> The "cheap copy" reference is only valid for the repository
> (back-end). So you should throw the word "repository" somewhere in
> that sentence :-).
Fixed in v3 patch.
> > Therefore, creating a
> > + new branch takes minimal time to complete and takes practically no
> > + space in the Subversion repository. You can create branches and use
> > + them for any change you want regardless of the change's size and scope.
> > + </p>
> > + <div class="h4" id="url-to-url-copy">
> > + <h4>
> > + Creating a branch using direct URL to URL copy
> > + <a class="sectionlink" href="#url-to-url-copy"
> > + title="Link to this section">¶</a>
> > + </h4>
> > + <p>
> > + Branching in Subversion is simple. In the simplest form, creating a
> > + new branch requires you to run the command against the remote
> > + repository's URLs. For example, let's create a new branch out of the
> > + mainline trunk:
> > + </p>
> > +<pre>
> > +$ svn copy https://example.com/MyRepo/trunk
> > https://example.com/MyRepo/branches/MyNewBranch -m "Creating a new
> > branch"
> > +</pre>
> > + </div>
> > + <div class="h4" id="WC-copy">
> > + <h4>
> > + Creating a branch through a working copy
> > + <a class="sectionlink" href="#WC-copy"
> > + title="Link to this section">¶</a>
> > + </h4>
> > + <p>
> > + When you interact with the remote central repository using your
> > + private local workspace - the working copy - you can use
> > + repository-relative URL instead of direct URL to URL copy to create
> > + a new branch:
> > + </p>
> > +<pre>
> > +$ svn copy "^/MyRepo/trunk" "^/MyRepo/branches/MyNewBranch" -m
> > "Creating a new branch"
> > +</pre>
>
> Hmmm, that's not what I consider "Creating a branch through a working
> copy". It's good to mention the repository-relative URL syntax
> somewhere. But I thought that section was about "Creating a branch
> *from* a working copy". Like:
>
> $ svn copy MyWork https://example.com/MyRepo/branches/OtherBranch -m "blabla"
>
> (potentially putting uncommitted changes directly in the branch).
> Though I'm not sure we should mention that here, and I think it's more
> often used for tags than for branches (creating a tag from a working
> copy that's been used for a build, so you have a snapshot of the exact
> sources that were used by your buildscripts).
>
> I think it might be better to drop #WC-copy, and perhaps add a section
> about the repository-relative url's (?). Not sure.
I would add a section about repository-relative URLs as a Tip or Note,
but not a whole section.
I've dropped #WC-copy in v3 patch. I think that we should mention it
in a Tag-specific section. The current version of the document does
not have it, though.
> Also, somewhere here you should probably mention that tags are very
> similar to branches (just another copy on the repository) ... the only
> thing discerning them is convention or policy (possibly enforced
> technically by the SVN administrator) to make tags read-only.
>
> > + </div>
> > + </div>
> > + <div class="h2" id="more-help">
> > + <h2>
> > + Getting more help
> > + <a class="sectionlink" href="#more-help"
> > + title="Link to this section">¶</a>
> > + </h2>
> > + <p>
> > + If you are new to Apache Subversion (SVN), read Version Control with
> > + Subversion book (SVNBook). SVNBook is the Bible of SVN and must-read
> > + for Subversion users and administrators. You can find SVNBook 1.8 at
> > + <a href="http://svnbook.red-bean.com/en/1.8/">http://svnbook.red-bean.com/en/1.8/</a>
> > + </p>
> > + </div>
> > + </div>
> > + </div> <!-- #site-content -->
> > </body>
> > </html>
>
>
> All in all, nice work!
>
> I think, now we got this far to explain branches, we should really
> also explain some basic 'merge' commands, very briefly (the two main
> usages: "complete" merges and "cherry-pick" merges, i.e. numbers 1 and
> 2 from 'svn help merge'). Also, I still would like to have a small
> section "Creating your own local repository" as a replacement of the
> current Quickstart guide. But those can happen in other commits /
> patches for sure.
Sure, I am going to continue with this task. The current version of
the document (as it is in v3 patch) is missing several important
sections that I thing about adding:
* Viewing the history of changes: provide `svn log` examples.
* Merging: automatic reintegration merges and cherry-picking.
* Tagging: we should provide tagging examples.
* Creating your own local repository: a quick guide on this task with
a link to SVNBook's High-Speed Tutorial.
> --
> Johan
--
With best regards,
Pavel Lyalyakin
VisualSVN Team
Re: [PATCH] Let's rework the Quick Start page (publish/quick-start.html)
Posted by Johan Corveleyn <jc...@gmail.com>.
On Fri, Sep 22, 2017 at 6:57 PM, Pavel Lyalyakin
<pa...@visualsvn.com> wrote:
> Hello,
>
> It appears that the current SVN Quick Start page[1] is kind of desolate; there
> is a discussion about updating it[2]. I want to volunteer for this task and I am
> attaching a patch. :)
>
> My idea is to provide novice SVN end users with a quick reference on the most
> basic concepts and operations:
> * checkout a working copy,
> * update the working copy,
> * modify the data in the working copy and commit it,
> * make a branch or tag.
>
> A user who needs help on how to begin working with SVN does not have to dive
> into the SVNBook. Yes, he will read the SVNBook some time later to learn more
> about basic operations and to find out about the magic of the complex ones. But
> not on his first day when the only commands he needs are `svn checkout` and
> `svn commit`.
>
> Log Message:
> [[[
> * publish/quick-start.html:
> Reworking the SVN Quick Start page as discussed in
> https://lists.apache.org/thread.html/da5b9f351a1bf2456aeb85e24ed88ff30b544a70995638af684684f1@%3Cdev.subversion.apache.org%3E
> ]]]
>
> [1]: https://subversion.apache.org/quick-start
> [2]: https://lists.apache.org/thread.html/da5b9f351a1bf2456aeb85e24ed88ff30b544a70995638af684684f1@%3Cdev.subversion.apache.org%3E
Hi Pavel,
Thanks again for taking this on. I'll try to give some feedback below.
> Index: publish/quick-start.html
> ===================================================================
> --- publish/quick-start.html (revision 1808237)
> +++ publish/quick-start.html (working copy)
> @@ -17,62 +17,433 @@
>
> <h1>Apache Subversion: Quick Start</h1>
>
> -<div class="h2" id="gui">
> -<h2>Graphical user interface (GUI) clients
> - <a class="sectionlink" href="#gui"
> - title="Link to this section">¶</a>
> -</h2>
> +<ul>
> + <li>
> + <a href="#installing-the-client">Installing the SVN client</a>
> + </li>
> + <li>
> + <a href="#understanding-the-terms">Understanding the terms</a>
I think "terms" can have the meaning of "terms of the agreement", or
"terms of the license". I think "terminology" is better. Maybe just
call this section "Terminology" (without the "understanding the ...").
> + </li>
> + <li>
> + <a href="#basic-tasks">Basic tasks</a>
> + </li>
> + <li>
> + <a href="#branching-and-tagging">Branching and tagging</a>
> + </li>
> + <li>
> + <a href="#more-help">Getting more help</a>
> + </li>
> +</ul>
>
> -<p>If you are not familiar with Subversion, you may be better served by a
> -graphical client. (The Subversion project only maintains a command-line-based
> -clients, but a number of third parties maintain graphical clients that build on
> -<a href="/docsapi/latest/">our API (for programmers)</a>.) We do not maintain
> -a list of such clients; instead, we recommend you do a Web search for
> -<tt>Subversion GUI client</tt>.
> -
> -</div>
> -
> -<div class="h2" id="bootstrap">
> -<h2>Make an existing directory a working copy of a new repository
> - <a class="sectionlink" href="#bootstrap"
> - title="Link to this section">¶</a>
> -</h2>
> -
> -<p>The following commands will convert a <tt>./my-directory/</tt> containing
> -files into a working copy of a newly-created repository:</p>
> -
> -<p>On Unix:</p>
> -
> + <div class="h2" id="installing-the-client">
> + <h2>
> + Installing the SVN client
> + <a class="sectionlink" href="#installing-the-client"
> + title="Link to this section">¶</a>
> + </h2>
> + <p>
> + Install the <tt>svn</tt> client to start collaborating on the project
"the project" -> "a project"
> + that is using Subversion as its version control system.
> + </p>
> + <p>
> + To install the client program, you can build it yourself from a source
> + code release or download a binary package. The list of sites where you
> + can obtain a pre-built Subversion client is available at the
> + <a href="/packages.html">official binary packages page</a>. If you want
> + to compile the software for yourself, grab the source at the
> + <a href="/source-code.html">Source Code</a> page.
> + </p>
> + <p>
> + Right after you install the client you should be able to test it by
> + issuing the svn command. You should see the following output:
> + </p>
> <pre>
> -$ mkdir -p $HOME/.svnrepos/
> -$ svnadmin create ~/.svnrepos/my-repos
> -$ svn mkdir -m "Create directory structure."
> file://$HOME/.svnrepos/my-repos/trunk
> file://$HOME/.svnrepos/my-repos/branches
> file://$HOME/.svnrepos/my-repos/tags
> -$ cd my-directory
> -$ svn checkout file://$HOME/.svnrepos/my-repos/trunk ./
> -$ svn add --force ./
> -$ svn commit -m "Initial import"
> -$ svn up
> +$ svn
> +Type 'svn help' for usage.
> </pre>
> + <p>
> + Now you can start using the command line client to interact with the
> + remote repository.
> + </p>
> + <div class="notice">
> + <p>
> + If you are not familiar with Subversion, you may be better served by a
> + graphical client. We do not maintain a list of such clients; instead,
> + we recommend you do a Web search for <tt>Subversion GUI</tt> client.
> + </p>
> + </div>
> + </div>
>
> -<p>On Windows:</p>
> + <div class="h2" id="understanding-the-terms">
> + <h2>
> + Understanding the terms
> + <a class="sectionlink" href="#understanding-the-terms"
> + title="Link to this section">¶</a>
> + </h2>
So let's say "Terminology" here.
> + <div class="h3" id="what-is-a-repository">
> + <h3>
> + What is a Repository?
> + <a class="sectionlink" href="#what-is-a-repository"
> + title="Link to this section">¶</a>
> + </h3>
> + <p>
> + The repository is a version control database that often resides on a
> + server and is usually exposed either by Apache HTTP Server
> + (mod_dav_svn) or svnserve server.
I'd say "by *an* Apache HTTP Server (*through the mod_dav_svn module*)
or *by an* svnserve server".
> The repository acts as a single
> + source of truth and – as a central storage – it contains the complete
> + history of changes of the versioned data in form of revisions.
> + </p>
> + <p>
> + Repository URL examples:
> + </p>
> + <ul>
> + <li>
> + Apache HTTP Server:
> <tt>https://svn.example.com/repos/MyRepo/MyProject/trunk</tt>
> + </li>
> + <li>
> + svnserve: <tt>svn://svn.example.com/repos/MyRepo/MyProject/trunk</tt>
> + </li>
> + <li>
> + Direct access (Unix-style):
> <tt>file://var/svn/repos/MyRepo/MyProject/trunk</tt>
> + </li>
> + <li>
> + Direct access (Windows-style):
> <tt>file:///C:/Repositories/MyRepo/MyProject/trunk</tt>
> + </li>
> + </ul>
Maybe not all of these examples should have the "MyProject/trunk",
because there is a lot of diversity out there. Maybe throw a
"/trunk/MyProject" in there, and a "/branches/mybranch" or
"/tags/1.1.0"?
> + </div>
> + <div class="h3" id="what-is-a-working-copy">
> + <h3>
> + What is a Working Copy?
> + <a class="sectionlink" href="#what-is-a-working-copy"
> + title="Link to this section">¶</a>
> + </h3>
> + <p>
> + The working copy is your local and private workspace that you use to
> + interact with the central Subversion repository. You use the working
> + copy to modify the contents of your project and fetch changes committed
> + by others.
> + </p>
> + <p>
> + The working copy contains your project's data and looks and acts like a
> + regular directory on your local file system, but with one major
> + difference - the working copy tracks the status and changes of files
> + and directories within. You can think of the working copy as of a
> + regular directory with version-control capabilities.
> + </p>
Maybe add a sentence to explain that Subversion keeps metadata in a
.svn directory in the root of the working copy, to manage those
version-control capabilities. (in case people start wondering how it
works, and how it's physically different from a regular directory).
> + <p>
> + There can be as much working copies from the same repository or project
> + as you want with any combination of local modifications.
> + </p>
> + </div>
> + </div>
>
> + <div class="h2" id="basic-tasks">
> + <h2>
> + Basic tasks
> + <a class="sectionlink" href="#basic-tasks"
> + title="Link to this section">¶</a>
> + </h2>
> + <div class="h3" id="importing-data">
> + <h3>
> + Importing data into the repository
> + <a class="sectionlink" href="#importing-data"
> + title="Link to this section">¶</a>
> + </h3>
> + <p>
> + In case you want to import an existing non-versioned data to SVN
Grammar tweak: drop the "an" before "existing", and add "an" before
SVN (and I'd say "*into* an SVN repository").
> + repository, you should run the
> + <a href="http://svnbook.red-bean.com/en/1.8/svn.ref.svn.c.import.html">
> + <tt>svn import</tt></a> command. Here is an example:
> + </p>
> <pre>
> -> mkdir C:\repos
> -> svnadmin create C:\repos\my-repos
> -> svn mkdir -m "Create directory structure."
> "file:///C:/repos/my-repos/trunk" "file:///C:/repos/my-repos/branches"
> "file:///C:/repos/my-repos/tags"
> -> cd my-directory
> -> svn checkout "file:///C:/repos/my-repos/trunk" ./
> -> svn add --force ./
> -> svn commit -m "Initial import"
> -> svn up
> +$ svn import https://svn.example.com/repos/MyRepo/MyProject/trunk -m
> "Initial project import"
> </pre>
> -
> -<p>See also <a
> -href="http://svnbook.red-bean.com/nightly/en/svn.intro.quickstart.html"
> ->quickstart instructions in The Subversion Book</a>.</p>
> -
> -</div> <!-- bootstrap -->
> -
> -</div> <!-- #site-content -->
> + </div>
> + <div class="h3" id="checking-out-a-working-copy">
> + <h3>
> + Checking out a working copy
> + <a class="sectionlink" href="#checking-out-a-working-copy"
> + title="Link to this section">¶</a>
> + </h3>
> + <p>
> + To begin making modifications to your project's data, you have to
> + create a local copy of the versioned project. You can use the command
> + line <tt>svn</tt> client or any GUI-based client that you prefer. Your
> + local copy of the project is called a working copy and
> + you create it by issuing the
> + <a href="http://svnbook.red-bean.com/en/1.8/svn.ref.svn.c.checkout.html">
> + <tt>svn checkout</tt></a> command. Here is an example:
> + </p>
> +<pre>
> +$ svn checkout https://svn.example.com/repos/MyRepo/MyProject/trunk
> +</pre>
> + <p>
> + As a result, you will get a working copy of the trunk of a project
> + called MyProject that resides in MyRepo repository. The working copy
> + will be located in MyProject directory on your computer. Note that
I think it will be located in a "trunk" directory on your computer.
Unless you do:
svn checkout https://svn.example.com/repos/MyRepo/MyProject/trunk MyProject
Though that might be a bit confusing, people might think the
"MyProject" argument is somehow special, while it's just the target
directory. Maybe something like "MyWork"? Or just say here that it'll
be located in a directory "trunk" (last path component as default
target dir)?
> + instead of checking out the trunk, you can check out some branch
> + or a tag (assuming they already exist in the repository).
> + </p>
> + <p>
> + You can get the working copy of the whole repository MyRepo, too. But
> + you should refrain from doing so. Generally speaking, you do not need
> + to have a working copy of the whole repository for your work because
> + your working copy can be instantly switched to another development
> + branch. Moreover, Subversion repository can contain a number of
> + unrelated projects and it is better to have a dedicated working copy
> + for each of them, not a single working copy for all of the projects.
Not to mention the repository database stores all different variations
of the code (branches, tags) in an efficient way. It's usually not a
good idea to check out all branches and tags onto a local disk as real
directories. Dunno if we should mention that here though ...
> + </p>
> + </div>
> + <div class="h3" id="updating-a-working-copy">
> + <h3>
> + Updating a working copy
> + <a class="sectionlink" href="#updating-a-working-copy"
> + title="Link to this section">¶</a>
> + </h3>
> + <p>
> + You are not the only person working on the project, right? This means
> + that your colleagues are also making modifications to the project's
> + data. To stay up to date and to fetch the modifications committed by
> + others, you should run the
> + <a href="http://svnbook.red-bean.com/en/1.8/svn.ref.svn.c.update.html">
> + <tt>svn update</tt></a> command in your working copy. As a result,
> + your working copy will sync with the repository and download the
> + changes made by your colleagues.
> + </p>
> + <p>
> + It is a rule to update your working copy before committing local
> + modifications to the repository.
No, I wouldn't say that. Maybe you could say that's "good practice" (I
think in general it is, though it depends I guess).
> + </p>
> + </div>
> + <div class="h3" id="making-changes">
> + <h3>
> + Making changes in your local working copy
> + <a class="sectionlink" href="#making-changes"
> + title="Link to this section">¶</a>
> + </h3>
> + <p>
> + Most of the time, you are going to perform modifications to the
> + project's data by modifying the contents of the working copy. As soon
> + as you are satisfied with the modifications and you've reviewed them
> + thoroughly, you are ready to publish them to the central repository.
Maybe you can already mention the word "commit" in that sentence?
Perhaps just say: "..., you are ready to commit them to the central
repository."
> + </p>
> + <div class="h4" id="modifying-existing-files">
> + <h4>
> + Modifying existing files
> + <a class="sectionlink" href="#modifying-existing-files"
> + title="Link to this section">¶</a>
> + </h4>
> + <p>
> + Modify the files as you usually do using your favorite text
> + processor, graphics editor, audio editing software, IDE, etc. As
> + soon as you save the changes to disk, Subversion will recognize them
> + automatically.
> + </div>
> + <div class="h4" id="committing-changes">
> + <h4>
> + Committing your changes to the repository
> + <a class="sectionlink" href="#committing-changes"
> + title="Link to this section">¶</a>
> + </h4>
> + <p>
> + In order to publish the changes you made in your working copy, you
> + should run the
> + <a href="http://svnbook.red-bean.com/en/1.8/svn.ref.svn.c.commit.html">
> + <tt>svn commit</tt></a> command.
> + </p>
> + <div class="notice">
> + <p>
> + Review your changes before committing them! Use the
> + <a
> href="http://svnbook.red-bean.com/en/1.8/svn.ref.svn.c.status.html">
> + <tt>svn status</tt></a> and
> + <a
> href="http://svnbook.red-bean.com/en/1.8/svn.ref.svn.c.diff.html">
> + <tt>svn diff</tt></a> commands to review the changes.
> + </p>
> + </div>
> + <p>
> + Here is an example of the commit command:
> + </p>
> +<pre>
> +$ svn commit -m "My Descriptive Log Message"
> +</pre>
> + <p>
> + Note the <tt>-m (--message)</tt> option. You must always include
> + descriptive commit log message. The log message has to help others
> + to understand why you made this commit, it has to contain a summary
> + of the changes you made.
The imperatives are a bit strong here. Perhaps rephrase it to: "You
should always include a descriptive commit log message. It should help
others (including your future self) understand why you made this
commit. Apart from the "why" it's a good idea to include a summary of
your changes in the log message."
Or something like that.
> + </p>
> + </div>
> + </div>
> + <div class="h3" id="performing-file-operations">
> + <h3>
> + Performing file operations
> + <a class="sectionlink" href="#performing-file-operations"
> + title="Link to this section">¶</a>
> + </h3>
Hmmm, this is not only about files, is it? Maybe you should name this
section "Performing tree changes", or "Performing file and directory
operations".
> + <p>
> + You can perform any actions with your project's data within the working
> + copy, but operations that involve copying, moving, renaming and
> + deleting must be performed using the corresponding <tt>svn</tt>
> + commands.
> + </p>
> + <div class="h4" id="adding-new-files">
> + <h4>
> + Adding new files
> + <a class="sectionlink" href="#adding-new-files"
> + title="Link to this section">¶</a>
> + </h4>
> + <p>
> + Put new files to the working copy and Subversion will recognize them
> + as unversioned. It will not automatically start tracking the new
> + files unless you run the
> + <a href="http://svnbook.red-bean.com/en/1.8/svn.ref.svn.c.add.html">
> + <tt>svn add</tt></a> command:
I think you can replace "files" with "files and directories" in the
above paragraph and title to make it a bit more general.
Also, I think "recognize them as unversioned" is a bit confusing (the
word "recognize" gives the impression that Subversion handles them
somehow). Maybe "Subversion will *see* them as 'unversioned'" (quoting
the word unversioned to point out it's a defined term).
> + </p>
> +<pre>
> +$ svn add foo.cs
> +</pre>
> + </div>
> + <div class="h4" id="moving-and-renaming-files-and-directories">
> + <h4>
> + Moving and renaming files and directories
> + <a class="sectionlink"
> href="#moving-and-renaming-files-and-directories"
> + title="Link to this section">¶</a>
> + </h4>
> + <p>
> + Move and rename files and directories using the
> + <a href="http://svnbook.red-bean.com/en/1.8/svn.ref.svn.c.move.html">
> + <tt>svn move</tt></a> or <tt>svn rename</tt> command:
> + </p>
> +<pre>
> +$ svn move foo.cs bar.cs
> +</pre>
> + <p>
> + The command <tt>svn rename</tt> is an alias for the
> + <tt>svn move</tt>.
> + </p>
Maybe a small word of warning should be put here: if you move a file
or directory with regular filesystem commands, Subversion will not
know about the move, and will just see an unrelated add and delete. To
get good results Subversion should be made aware of moves, so it can
track them in its metadata (this is a definite difference from the
heuristic-tracking DVCS'es ... Subversion requires explicit tracking
of tree changes).
> + </div>
> + <div class="h4" id="copying-files-and-directories">
> + <h4>
> + Copying files and directories
> + <a class="sectionlink" href="#copying-files-and-directories"
> + title="Link to this section">¶</a>
> + </h4>
> + <p>
> + Copy files and directories using the
> + <a href="http://svnbook.red-bean.com/en/1.8/svn.ref.svn.c.copy.html">
> + <tt>svn copy</tt></a> command:
> + </p>
> +<pre>
> +$ svn copy foo.cs bar.cs
> +</pre>
The above is a bit tricky, as 'svn copy' also creates a branch of the
copied item, and the line of history is split (or put another way: the
copied item is linked to the same pre-copy history). It's a bit
difficult to explain all this in a quick start guide, unless you have
some ideas.
Maybe it's good as it is, but OTOH I've seen that often users are
surprised by this (and really just wanted to copy the file contents,
but not make it historically related to the original file).
Maybe we should just drop this section "copying files and directories"
for now? ('svn copy' is also mentioned later on in the "branching"
section)
> + </div>
> + <div class="h4" id="deleting-files-and-directories">
> + <h4>
> + Deleting files and directories
> + <a class="sectionlink" href="#deleting-files-and-directories"
> + title="Link to this section">¶</a>
> + </h4>
> + <p>
> + Delete files and directories using the svn delete
> + <a href="http://svnbook.red-bean.com/en/1.8/svn.ref.svn.c.delete.html">
> + <tt>svn delete</tt></a> command:
> + </p>
> +<pre>
> +$ svn delete foo.cs
> +</pre>
Maybe here too, a small warning that if you delete files or
directories with regular filesystem commands, Subversion will not know
about the delete. It will regard the item as "missing" (having
metadata but no corresponding file), and will bring it back on the
next 'svn update'.
> + </div>
> + <div class="h4" id="reverting-local-changes">
> + <h4>
> + Reverting or discarding local changes
> + <a class="sectionlink" href="#reverting-local-changes"
> + title="Link to this section">¶</a>
> + </h4>
> + <p>
> + Revert your local uncommitted changes using the
^^ Maybe say "Discard your local ...", so it's immediately clear what
'svn revert' does.
> + <a href="http://svnbook.red-bean.com/en/1.8/svn.ref.svn.c.revert.html">
> + <tt>svn revert</tt></a> command:
> + </p>
> +<pre>
> +$ svn revert foo.cs
> +</pre>
> + <div class="notice">
> + <p>
> + Discarded uncommitted changes will be lost forever. You
> will not be
> + able to recover the reverted changes. Use <tt>svn revert</tt> with
> + caution!
> + </p>
> + </div>
> + </div>
> + </div>
> + <div class="h3" id="branching-and-tagging">
> + <h3>
> + Branching and tagging
> + <a class="sectionlink" href="#branching-and-tagging"
> + title="Link to this section">¶</a>
> + </h3>
> + <p>
> + You should use the <tt>svn copy</tt> command to create branches and
> + tags. This is the same command that is used to copy items in your
> + working copy and in the repository.
... if you want them to be historically related (?)
> + </p>
> + <p>
> + The command <tt>svn copy</tt> is used for branching because, branch is
> + technically a copy of the source you copy from. However, this is not
> + an ordinary copy are familiar with when copying files on your local
> + file system.
There's a word missing in the above sentence.
> Branches in Subversion are so called
> + <a href="http://svnbook.red-bean.com/en/1.8/svn.branchmerge.using.html#svn.branchmerge.using.create">
> + "Cheap Copies"</a> that are similar to symlinks.
The "cheap copy" reference is only valid for the repository
(back-end). So you should throw the word "repository" somewhere in
that sentence :-).
> Therefore, creating a
> + new branch takes minimal time to complete and takes practically no
> + space in the Subversion repository. You can create branches and use
> + them for any change you want regardless of the change's size and scope.
> + </p>
> + <div class="h4" id="url-to-url-copy">
> + <h4>
> + Creating a branch using direct URL to URL copy
> + <a class="sectionlink" href="#url-to-url-copy"
> + title="Link to this section">¶</a>
> + </h4>
> + <p>
> + Branching in Subversion is simple. In the simplest form, creating a
> + new branch requires you to run the command against the remote
> + repository's URLs. For example, let's create a new branch out of the
> + mainline trunk:
> + </p>
> +<pre>
> +$ svn copy https://example.com/MyRepo/trunk
> https://example.com/MyRepo/branches/MyNewBranch -m "Creating a new
> branch"
> +</pre>
> + </div>
> + <div class="h4" id="WC-copy">
> + <h4>
> + Creating a branch through a working copy
> + <a class="sectionlink" href="#WC-copy"
> + title="Link to this section">¶</a>
> + </h4>
> + <p>
> + When you interact with the remote central repository using your
> + private local workspace - the working copy - you can use
> + repository-relative URL instead of direct URL to URL copy to create
> + a new branch:
> + </p>
> +<pre>
> +$ svn copy "^/MyRepo/trunk" "^/MyRepo/branches/MyNewBranch" -m
> "Creating a new branch"
> +</pre>
Hmmm, that's not what I consider "Creating a branch through a working
copy". It's good to mention the repository-relative URL syntax
somewhere. But I thought that section was about "Creating a branch
*from* a working copy". Like:
$ svn copy MyWork https://example.com/MyRepo/branches/OtherBranch -m "blabla"
(potentially putting uncommitted changes directly in the branch).
Though I'm not sure we should mention that here, and I think it's more
often used for tags than for branches (creating a tag from a working
copy that's been used for a build, so you have a snapshot of the exact
sources that were used by your buildscripts).
I think it might be better to drop #WC-copy, and perhaps add a section
about the repository-relative url's (?). Not sure.
Also, somewhere here you should probably mention that tags are very
similar to branches (just another copy on the repository) ... the only
thing discerning them is convention or policy (possibly enforced
technically by the SVN administrator) to make tags read-only.
> + </div>
> + </div>
> + <div class="h2" id="more-help">
> + <h2>
> + Getting more help
> + <a class="sectionlink" href="#more-help"
> + title="Link to this section">¶</a>
> + </h2>
> + <p>
> + If you are new to Apache Subversion (SVN), read Version Control with
> + Subversion book (SVNBook). SVNBook is the Bible of SVN and must-read
> + for Subversion users and administrators. You can find SVNBook 1.8 at
> + <a href="http://svnbook.red-bean.com/en/1.8/">http://svnbook.red-bean.com/en/1.8/</a>
> + </p>
> + </div>
> + </div>
> + </div> <!-- #site-content -->
> </body>
> </html>
All in all, nice work!
I think, now we got this far to explain branches, we should really
also explain some basic 'merge' commands, very briefly (the two main
usages: "complete" merges and "cherry-pick" merges, i.e. numbers 1 and
2 from 'svn help merge'). Also, I still would like to have a small
section "Creating your own local repository" as a replacement of the
current Quickstart guide. But those can happen in other commits /
patches for sure.
--
Johan