On Fri, Sep 22, 2017 at 6:57 PM, Pavel Lyalyakin
<pavel.lyalyakin_at_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>
> + Installing the SVN client
> + </li>
> + <li>
> + Understanding the terms
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>
> + Basic tasks
> + </li>
> + <li>
> + Branching and tagging
> + </li>
> + <li>
> + Getting more help
> + </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
> -our API (for programmers).) 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
> + official binary packages page. If you want
> + to compile the software for yourself, grab the source at the
> + Source Code 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
> + http://svnbook.red-bean.com/en/1.8/
> + </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
Received on 2017-09-26 02:05:45 CEST