[MacPorts] CommittersTipsAndTricks modified

[MacPorts]

Changed page "CommittersTipsAndTricks" by dweber at macports.org from 206.176.233.167*
Page URL: <http://trac.macports.org/wiki/CommittersTipsAndTricks>
Diff URL: <http://trac.macports.org/wiki/CommittersTipsAndTricks?action=diff&version=28>
Revision 28

-------8<------8<------8<------8<------8<------8<------8<------8<--------
Index: CommittersTipsAndTricks
=========================================================================
--- CommittersTipsAndTricks (version: 27)
+++ CommittersTipsAndTricks (version: 28)
@@ -19,31 +19,31 @@
 }}}
 
 
-== Create your own users directory in the MacPorts Subversion repository ==
+== Create an experimental users directory in the MacPorts Subversion repository ==
 
 Use the [/browser Trac Browser] to explore the MacPorts Subversion repository. The repository root is located at `https://svn.macosforge.org/repository/macports`.
 
 See also the explanation of [http://guide.macports.org/#development.local-repositories local development port trees] in the guide.
 
-To create your own users directory:
+To create a sandbox for experimental development, create a users directory:
 
 {{{
 svn mkdir https://svn.macports.org/repository/macports/users/<YourMacPortsUserName>
 }}}
 
-Then, checkout your user directory:
+Then, checkout the user directory (suggested location is ~/myports):
 
 {{{
 $ svn co https://svn.macports.org/repository/macports/users/<YourMacPortsUserName> ~/myports
 }}}
 
-Then edit your MacPorts sources.conf file {{{/opt/local/etc/macports/sources.conf}}} to add ~/myports to the list before the main rsync source at rsync.macports.org, e.g.:
-
-{{{
-file:///Users/<YourSystemUserName>/myports
-}}}
-
-To work on a copy of a port from MacPorts trunk, use `svn copy`.  For example, to test changes on the cableswig port, you can copy the repository trunk (at the HEAD revision) to your new user branch:
+Then edit the MacPorts sources.conf file {{{/opt/local/etc/macports/sources.conf}}} to add ~/myports to the list before the main rsync source at rsync.macports.org, e.g.:
+
+{{{
+file:///Users/<YourSystemUserName>/myports [nosync]
+}}}
+
+To work on a copy of a port from the MacPorts trunk, use `svn copy`.  For example, to test changes on the cableswig port, copy the repository trunk (at the HEAD revision) into the user branch:
 
 {{{
 $ svn mkdir ~/myports/devel
@@ -56,12 +56,12 @@
 $ svn copy \
       https://svn.macosforge.org/repository/macports/trunk/dports/devel/cableswig \
       https://svn.macports.org/repository/macports/users/<YourMacPortsUserName>/devel/cableswig \
-      -m "testing modifications to cableswig"
+      -m "experimental modifications to cableswig"
 $ cd ~/myports
 $ svn update
 }}}
 
-After the copy, run `portindex` in `~/myports` (do this any time you add a new Portfile), e.g.:
+After the copy, run `portindex` in `~/myports` (do this anytime ports are added or removed from ~/myports), e.g.:
 
 {{{
 $ cd ~/myports
@@ -69,6 +69,65 @@
 $ portindex
 $ port file cableswig
 }}}
+
+Now make experimental changes to the port in the sandbox.  Whenever a signficant change is made, note the change with a commit to the sandbox and when all the changes are complete commit the final change to the sandbox with a meaningful commit message.
+
+The main trunk Portfile and the sandbox Portfile are now out of sync.  Someone may make changes to the main trunk Portfile while changes are made to the sandbox Portfile.  Let's assume that all the experimental changes are successful, so the Portfile needs to be integrated back into the main trunk, where other changes may have occurred.  This merge process requires a few steps.  Let's assume there are checkouts for the sandbox in ~/myports and the trunk in ~/macports.
+
+First update the sandbox and the trunk checkouts, e.g.:
+
+{{{
+cd ~/myports
+svn update
+cd ~/macports
+svn update
+}}}
+
+Note that the revision numbers should be the same (because the sandbox and the main trunk belong to the same svn repository).
+
+Next, find out where the experimental changes left off from the trunk and create a bash variable (any shell variable) to store the value of the revision number where the branch copy occurred (the revision number will be the last one in the log):
+
+{{{
+cd ~/myports/devel/cableswig
+svn log --stop-on-copy Portfile
+EXP_BRANCH_REV=54362
+}}}
+
+For the curious, leave off the `--stop-on-copy` to see the entire commit log history (it should all be there if there is a continuous and reliable use of svn to manage the file from it's "birth" in the svn repository).
+
+Now take a look at the commit log for the main trunk, to get some hints about what has changed to the file since the experimental branch was forked off.
+
+{{{
+cd ~/macports/dports/devel/cableswig
+svn log Portfile | more
+}}}
+
+Look through the log to find the revision number where the experimental copy took place.  If that is the first revision number in the log, there have been no changes in the trunk.  Otherwise, changes have occurred in the trunk that are not in the experimental branch.  There could be trunk changes that complement the experimental branch, or they may be in conflict.  Try to merge all these changes using the revision number of the experimental copy:
+
+{{{
+cd ~/macports/dports/devel/cableswig
+svn merge  -r ${EXP_BRANCH_REV}:HEAD  https://svn.macosforge.org/repository/macports/users/<YourMacPortsUserName>/devel/cableswig/Portfile Portfile
+}}}
+
+Now resolve any conflicts, if any, in the trunk Portfile.  All work continues in the trunk (until the next time a sandbox is required).  Once the merge looks good, commit all the changes to the trunk with a meaningful commit message,
+
+{{{
+cd ~/macports/dports/devel/cableswig
+svn commit "merged sandbox changes from ${EXP_BRANCH_REV}:HEAD back into trunk" Portfile
+}}}
+
+Finally, to have the port system revert to using the rsync distribution, it's possible to remove the sandbox port.  No information is lost from the svn system, so removing the sandbox port is really harmless (in any case, all the changes are now back in the trunk).  For example,
+
+{{{
+sudo port clean --all cableswig
+cd ~/myports/devel
+svn remove cableswig
+svn commit -m "done with sandbox for cableswig"
+svn update
+cd ~/myports
+portindex
+}}}
+
 
 For more information about branches and merging, see
 http://svnbook.red-bean.com/en/1.5/svn.branchmerge.html

-------8<------8<------8<------8<------8<------8<------8<------8<--------

* The IP shown here might not mean anything if the user or the server is
behind a proxy.

--
MacPorts <http://www.macports.org/>
Ports system for Mac OS

This is an automated message. Someone at http://www.macports.org/ added your email
address to be notified of changes on CommittersTipsAndTricks. If it was not you, please
report to .