编辑“Gallery:使用Subversion”

== Subversion是什么？ ==

[http://subversion.tigris.org/ Subversion]是一个修正控制系统—使我们在进行代码操作时可以对操作历史进行追踪。我们可以使用它来回顾任何时候所作的修改，并知晓曾做过什么，何时做的以及进行此操作的原因。修正控制系统是软件开发中不可或缺的一部分。


== 如何获取最新的代码？ ==
 
为了能够进行这些指导操作，你需要在Unix系统上的一个shell帐户。如果你使用的是Windows，你应当先参考一下我们的[[Gallery:Using_Subversion_on_Windows|Windows上Subversion]]的相关指导。如果你使用Eclipse作为IDE的话，你需要参读一下[[Gallery:Eclipse_Tutorial#Using_SVN_and_creating_your_Gallery2_Project_based_on_our_sourceforge_SVN_Repository|Eclipse中的Subversion]]。Mac OS X的用户应当参看此页内容以加深对Subversion的了解，同时请参看一下我们的[[Gallery:Using_Subversion_on_Macs|Mac上Subversion的相关指导]]。

我们的subversion库被分为几个区域。每个区都围绕项目计划中的某个特定的产品或概念。现有区域如下：

{| class="gallery" style="background-color: #eee"
! align="left" | 名称 !! align="left" | 描述
|-
| gallery || Gallery 1.x
|-
| gallery2 || Gallery 2.x，Gallery次世代
|-
| gallery_remote || Gallery Remote的java客户端
|-
| 整合 || 用以将G2同其他应用程序 整合在一起的模块
|-
| docs || Gallery 1.x的documentation模块
|-
| 打包 || Gallery 1.x与Gallery 2.x发布的脚本
|}

一旦你选择好了，就可以通过一个svn checkout获得一个复本。如果你想得到最新的Gallery2代码：

  <nowiki>svn checkout https://gallery.svn.sourceforge.net/svnroot/gallery/trunk/gallery2</nowiki>

注意，这里的URL使用的是'''HTTPS'''协议而不是HTTP。你可将此例中的"gallery2"替换为上表中的区域名称。但请注意checkout无法覆盖已有文件（自non-svn安装）。
更多有关Gallery1的Subversion信息请参看[[Gallery1:Developer_Guide]].

<toggle title="Information about &quot;Secure connections truncated&quot; errors">
如果你使用正确的URL host部分（新）而非过期的（旧）话，那么自2006年10月26日之后，此来自svn命令的错误就不应再出现了：

  <nowiki>新：svn checkout https://gallery.svn.sourceforge.net/svnroot/gallery/trunk/....
  旧： svn checkout https://svn.sourceforge.net/svnroot/gallery/trunk/....</nowiki>

参见[https://sourceforge.net/tracker/index.php?func=detail&aid=1538801&group_id=1&atid=200001 Subversion proxying的相关问题]来看看Sourceforge方面的解释及解决方案（非常感谢SF的工作！）。

如果你仍使用过期的/旧的URL复本的话，那么请按照[https://www.sourceforge.net/docs/E09#notice SourceForge SVN documentation]中给出的指导进行操作。
</toggle>


=== 如何在web浏览器中查看代码？ ===

想查看一下代码的修正历史吗？ http://gallery.svn.sourceforge.net/viewvc/gallery/

== 如何更新代码？ ==

如果你刚做了一个"checkout"的话，那么情况就都已确定了。但如果过了一段时间你希望获取最新代码的话，那么你可以打开代码所在的文件夹并输入：

  svn update
来保持代码的更新。

你会看到类似这样的回复
  U index.php
  U main.php
  U embed.php
  ...  

这将带给你最新版本的代码。你所接收的每份文件都会附带一个字母，告知你Subversion该如何进行处理。这些字母[http://svnbook.red-bean.com/nightly/en/svn-book.html#svn.tour.cycle.update 在此有详细的解释]。大部分情况下，文件将会被标记一个字母<b>U</b>，表示它们已进行更新了。如果你对文件进行了修改，而你所作的修改与我们所作的修改有冲突的话，就会看到文件被标记上了字母<b>C</b>。

=== 如果出现了冲突该怎么办？ ===

当你所作的代码修改与Gallery团队所作的修改发生冲突时，Subversion无法自主解决问题。在这种情况下，Subversion用字母<b>C</b>标记这些有冲突的文件，而且得靠你自己来解决问题。Subversion book当中有关[http://svnbook.red-bean.com/nightly/en/svn-book.html#svn.tour.cycle.resolve 如何解决冲突]的部分十分有用。这里给出一个简短的例子。如果你和我们同时修改了index.php你就会得到这样的链接：

  C  index.php

如果进行查看的话，就会看到类似这样的文件：

  ls -al index*
  index.php
  index.php.mine
  index.php.r1
  index.php.r2

实际的数字（r1，r2）可能会不同。较小的数字表示的是存储库中较老版本的文件，较大的数字则代表较新版本的文件。.mine文件是Subversion试图合并之前的你的文件，而index.php则包含Subversion进行合并的最佳尝试。你会在index.php文件中看到：

  <<<<<<< .mine
  /* 你所作的某修改 */
  =======
  /* Gallery所作的某修改*/
  >>>>>>> .r2

有必要在了解你自己所作修改的同时也了解一下Gallery所作的修改，然后确定如何能够让二者并行不悖。合并操作的难度完全取决于你所作修改的程度。

一旦你完成了文件的合并，就可以通过：

  svn resolved index.php

问题解决了。

这看起来着实有些麻烦，但并无妨害。Subversion将替你完成所有简单的合并操作—仅仅给你留下了困难的。如果你对代码所作的修改不是很大的话，那根本就不会发生什么冲突。


== 可以为我的Gallery使用Subversion吗？ ==

当然可以！而且这是个不错的主意。这让你的代码升级变的既快又简单了，而且你对代码所作的任何修改都将在升级时被保留下来。如果你希望能有一个稳定点的Gallery，我们建议你跟踪主要发行版本的分支。这将保证在你升级更新时，仅最小且必要的修正将用于主要发行版本问题的解决（如安全性更新或致命BUG的修复）。

=== 何为主要发行版本分支？ ===

Subversion有一个被称为[http://svnbook.red-bean.com/nightly/en/svn-book.html#svn.branchmerge.what 分支（branch）]的特点。这些都是独立平行的代码复本，它们是各行其道的。每次我们发布一个主要版本时（如2.0和2.2），我们都会为它创建一个分支（比如BRANCH_2_0和BRANCH_2_2)。这样你就可以让Subversion为你找到相应版本的代码了。如果你希望从Subversion存储库中获取Gallery2.2的话，就需要使用如下命令行：

  <nowiki>svn checkout https://gallery.svn.sourceforge.net/svnroot/gallery/branches/BRANCH_2_2/gallery2/ .</nowiki>

这将为你找出最新的Gallery2.2代码复本。这跟你下载Gallery2开发者整合包的效果几乎是一样的。

=== 如何保证一个分支的更新？ ===

只要我们新发布一个较小版本时（比如2.1.1），我们都会更新其在主要发布版本分支中的代码。因此当我们发布2.1.1时，2.1和2.1.1版本的所有区别都在BRANCH_2_1中。这意味着，如果你选择的是BRANCH_2_1，你所需要做的只是一个"svn更新"，然后就能更新到2.1.1版本了。此方法的效率可见一斑。在小的更新版本中，我们正尝试做较小的， API兼容性的修改。这样你在一个分支版本中就能够一直进行安全的升级了。这种情况下，你<b>不会</b>得到任何实验代码。

=== 如何转换为下个主要发布版本分支？ ===

假设你选择BRANCH_2_0安装的2.0并且做了一些较小的修改。现在你希望升级到2.1.1版本的最新代码。你可以告知Subversion转换为BRANCH_2_1，方法如下：
  cd gallery
  <nowiki>svn switch https://gallery.svn.sourceforge.net/svnroot/gallery/branches/BRANCH_2_1/gallery2</nowiki>

现在你就有了2.1版本的代码了，而且仍保留了你在2.0代码中做出的修改。此命令发出的回复与svn更新时的回复很相似。请参考[[Gallery:Using_Subversion#How_do_I_update_the_code.3F|有关更新的描述部分]]来看看如何阅读结果。


== 如果降低SVN checkout的磁盘空间占有率？ ==

下载并解压[[Media:SvnSlim.zip|SvnSlim.zip]]，将 <tt>svnSlim</tt> 置入路径下的一个目录中。参见脚本顶部的指导。svnSlim创建一个gallery2的checkout，它省略了单元测试和语言文件（使用-L {locale}可选地包含一个语言）。checkout完成后，你可以运行<tt>svnSlim slim</tt>来移除subversion维护的所有文件的第二份复本。此方法将节省很多磁盘空间，但同时你就不能使用某些svn命令了（如<tt>svn diff</tt>），除非你使用<tt>svnSlim fat</tt>恢复这些文件。要更新一个svnSlim checkout的话，运行<tt>svnSlim update</tt>。无论是"slim"或"fat"都会运行。


== 如何由CVS迁移到Subversion？ ==

基本的打算是将你gallery的CVS版本指定一个已知点，接着将其转移到Subversion中相符的点上。完成此操作不会丢失你对代码所作的任何修改。以下给出的指导是假设你的代码位于'''gallery2'''目录下的情况，请根据实际情况区别对待。

在sourceforge上更新至最新版本的CVS：
  cvs -t -d :pserver:anonymous@gallery.cvs.sourceforge.net:/cvsroot/gallery update

请注意你应当提供新的-d标志，因为SourceForge在2006年5月12日换了一组新的CVS服务器（由于硬件故障）并且修改了CVS的路径。

接着讲你的代码移除
  mv gallery2 gallery2-cvs

然后从subversion截取相符的代码。由CVS的头部部分移动到Subversion主干部分：
  svn checkout -r 13519 <nowiki>https://gallery.svn.sourceforge.net/svnroot/gallery/trunk/gallery2</nowiki>

或者如果你从一个分支（如BRANCH_2_1）进行移动操作的话，你应当这样：
  svn checkout -r 13519 <nowiki>https://gallery.svn.sourceforge.net/svnroot/gallery/branches/BRANCH_2_1/gallery2</nowiki>

接着复制你所作的修改到subversion中。此命令将全盘复制你的cvs实体到subversion实体中去，不过除了CVS dir（因为这些已经不需要了）：
  cd gallery2-cvs
  tar --exclude CVS -cf - . | ( cd ../gallery2 && tar -xvf - )

现在你就可以在浏览器中浏览你的gallery2目录了，而且该怎样运行的还是照旧那么运行。然而，SVN和CVS在处理关键词方面有微妙的差别，因此要做适当修正的话你应当按如下的方法操作。但是请注意此方法仅在HEAD->trunk的情况下测试过 .. 因此如果对于分支来说的话，情况可能会有所偏差。以下的命令修复存在于所有文件中的$RCSfile$关键词，然后会放弃对部分无法修复文件的修改。
  cd gallery2
  perl -pi -e 's/(\$RCSfile):.*?\$/$1\$/' `find . -name "*.php" -print -o -name "*.inc" -print -o -name "*.class" -print -o -name "*.js" -print` install/config.php-template themes/ajaxian/theme.css lib/tools/creator/*.tpl lib/tools/uml/JavaClasses.xsl
  svn revert modules/core/test/phpunit/AdminRepository* modules/picasa/classes/*ss modules/picasa/test/phpunit/*ss

现在通过如下操作你就能看到所作修改的列表：
  svn status

你的Gallery应该能正常运行了。要将你跟踪的语句中的代码更新的话，你应当：
  svn update

== 如何由non-svn转为svn？ ==

* [http://gallery.menalto.com/node/57452 http://gallery.menalto.com/node/57452]

== 开发者信息 ==

编辑你的 ~/.subversion/config文件并将如下语句行合并到<tt>[auto-props]</tt>部分。如此这般，在添加新文件时，svn属性将会被合理地设定。

<pre>
[auto-props]
*.php = svn:keywords=Author Id Revision;svn:eol-style=native
*.inc = svn:keywords=Author Id Revision;svn:eol-style=native
*.class = svn:keywords=Author Id Revision;svn:eol-style=native
*.tpl = svn:keywords=Author Id Revision;svn:eol-style=native
*.html = svn:keywords=Author Id Revision;svn:eol-style=native
*.css = svn:keywords=Author Id Revision;svn:eol-style=native
*.js = svn:keywords=Author Id Revision;svn:eol-style=native
*.txt = svn:eol-style=native
*.xml = svn:eol-style=native
MANIFEST = svn:keywords=Author Id Revision;svn:eol-style=native
GNUmakefile = svn:keywords=Author Id Revision;svn:eol-style=native
strings.raw = svn:keywords=Author Id Revision;svn:eol-style=native
*.po = svn:keywords=Author Id Revision;svn:eol-style=native
*.mo = svn:mime-type=application/octet-stream
*.gif = svn:mime-type=image/gif
*.png = svn:mime-type=image/png
*.jpg = svn:mime-type=image/jpeg
</pre>

注：Gallery不会使用上述设定中的"日期（Date）"关键词，因为根据区域设置的不同，输出也会不一样，从而可能会导致svn安装中文件完整性检查时出问题。

最后，'''如果你希望启用auto-props的话'''，请记得将<tt>[miscellany]</tt>部分中的'''enable-auto-props设置为是（yes）'''

对于Windows用户，每个用户的config文件一般都能在如下路径中找到：

<pre>
C:\Documents and Settings\<YOUR_LOGIN>\Application Data\Subversion\config
</pre>

对于其他语言版本的Windows例子，如果是德语语言的用户，路径就是：

<pre>
C:\Dokumente und Einstellungen\<YOUR_LOGIN>\Anwendungsdaten\Subversion\config
</pre>



%APPDATA% 是对应你的"Application Data"目录的环境变量。将如下语句复制到任何Explorer窗口的地址栏中，最终将会直接打开上述例子中的文件夹，而无需在意Windows所使用的语言。
<pre>
%APPDATA%\Subversion\config
</pre>

如果你使用的是[[Gallery:Using_Subversion_on_Windows|Windows]]，[[Gallery:Eclipse_Tutorial|Eclipse]]和[[Gallery:Eclipse_Tutorial#Using_SVN_and_creating_your_Gallery2_Project_based_on_our_sourceforge_SVN_Repository|Subclipse Plugin]]以及JavaHL系结（可能还包括JavaSVN系结，不过我没有进行过亲测）的话，用此方法查找config文件也是可以的。