doc/savannah.txt

   1 Daily Use Guide for using Savannah for lwIP
   2
   3 Table of Contents:
   4
   5 1 - Obtaining lwIP from the CVS repository
   6 2 - Committers/developers CVS access using SSH (to be written)
   7 3 - Merging from DEVEL branch to main trunk (stable branch)
   8 4 - How to release lwIP
   9
  10
  11
  12 1 Obtaining lwIP from the CVS repository
  13 ----------------------------------------
  14
  15 To perform an anonymous CVS checkout of the main trunk (this is where
  16 bug fixes and incremental enhancements occur), do this:
  17
  18 export CVS_RSH=ssh
  19 cvs -d:ext:anoncvs@subversions.gnu.org:/cvsroot/lwip checkout lwip
  20
  21 (If SSH asks about authenticity of the host, you can check the key
  22  fingerprint against http://savannah.nongnu.org/cvs/?group=lwip)
  23
  24 Or, obtain a stable branch (updated with bug fixes only) as follows:
  25 cvs -d:ext:anoncvs@subversions.gnu.org:/cvsroot/lwip checkout -r STABLE-0_7 -d lwip-0.7 lwip
  26
  27 Or, obtain a specific (fixed) release as follows:
  28 cvs -d:ext:anoncvs@subversions.gnu.org:/cvsroot/lwip checkout -r STABLE-0_7_0 -d lwip-0.7.0 lwip
  29
  30 Or, obtain a development branch (considered unstable!) as follows:
  31 cvs -d:ext:anoncvs@subversions.gnu.org:/cvsroot/lwip checkout -r DEVEL -d lwip-DEVEL lwip
  32
  33 3 Committers/developers CVS access using SSH
  34 --------------------------------------------
  35
  36 The Savannah server uses SSH (Secure Shell) protocol 2 authentication and encryption.
  37 As such, CVS commits to the server occur through a SSH tunnel for project members.
  38 To create a SSH2 key pair in UNIX-like environments, do this:
  39
  40 ssh-keygen -t dsa
  41
  42 Under Windows, a recommended SSH client is "PuTTY", freely available with good
  43 documentation and a graphic user interface. Use its key generator.
  44
  45 Now paste the id_dsa.pub contents into your Savannah account public key list. Wait
  46 a while so that Savannah can update its configuration (This can take minutes).
  47
  48 Try to login using SSH:
  49
  50 ssh -v your_login@subversions.gnu.org
  51
  52 If it tells you:
  53
  54 Authenticating with public key "your_key_name"...
  55 Server refused to allocate pty
  56
  57 then you could login; Savannah refuses to give you a shell - which is OK, as we
  58 are allowed to use SSH for CVS only. Now, you should be able to do this:
  59
  60 export CVS_RSH=ssh
  61 cvs -d:ext:your_login@subversions.gnu.org:/cvsroot/lwip checkout lwip
  62
  63 after which you can edit your local files with bug fixes or new features and
  64 commit them. Make sure you know what you are doing when using CVS to make
  65 changes on the repository. If in doubt, ask on the lwip-members mailing list.
  66
  67 3 Merging from DEVEL branch to main trunk (stable)
  68 --------------------------------------------------
  69
  70 Merging is a delicate process in CVS and requires the
  71 following disciplined steps in order to prevent conflicts
  72 in the future. Conflicts can be hard to solve!
  73
  74 Merging from branch A to branch B requires that the A branch
  75 has a tag indicating the previous merger. This tag is called
  76 'merged_from_A_to_B'. After merging, the tag is moved in the
  77 A branch to remember this merger for future merge actions.
  78
  79 IMPORTANT: AFTER COMMITTING A SUCCESFUL MERGE IN THE
  80 REPOSITORY, THE TAG MUST BE SET ON THE SOURCE BRANCH OF THE
  81 MERGE ACTION (REPLACING EXISTING TAGS WITH THE SAME NAME).
  82
  83 Merge all changes in DEVEL since our last merge to main:
  84
  85 In the working copy of the main trunk:
  86 cvs update -P -jmerged_from_DEVEL_to_main -jDEVEL
  87
  88 (This will apply the changes between 'merged_from_DEVEL_to_main'
  89 and 'DEVEL' to your work set of files)
  90
  91 We can now commit the merge result.
  92 cvs commit -R -m "Merged from DEVEL to main."
  93
  94 If this worked out OK, we now move the tag in the DEVEL branch
  95 to this merge point, so we can use this point for future merges:
  96
  97 cvs rtag -F -r DEVEL merged_from_DEVEL_to_main lwip
  98
  99 4 How to release lwIP
 100 ---------------------
 101
 102 First, checkout a clean copy of the branch to be released. Tag this set with
 103 tag name "STABLE-0_6_3". (I use release number 0.6.3 throughout this example).
 104
 105 Login CVS using pserver authentication, then export a clean copy of the
 106 tagged tree. Export is similar to a checkout, except that the CVS metadata
 107 is not created locally.
 108
 109 export CVS_RSH=ssh
 110 cvs -d:ext:anoncvs@subversions.gnu.org:/cvsroot/lwip export -r STABLE-0_6_3 -d lwip-0.6.3 lwip
 111
 112 Archive this directory using tar, gzip'd, bzip2'd and zip'd.
 113
 114 tar czvf lwip-0.6.3.tar.gz lwip-0.6.3
 115 tar cjvf lwip-0.6.3.tar.bz2 lwip-0.6.3
 116 zip -r lwip-0.6.3.zip lwip-0.6.3
 117
 118 First, make a local release directory to work in, I use "lwip-releases":
 119
 120 mkdir lwip-releases
 121 cd lwip-releases
 122
 123 Now, make a new release by creating a new directory for it (these are
 124 Savannah conventions so that it shows up in the Files list real nice):
 125
 126 mkdir stable.pkg
 127 mkdir stable.pkg 0.6.3
 128
 129 We can now copy the tar archive we made earlier into the release directory:
 130
 131 cp ../../../lwip-0.6.3.tar.gz .
 132
 133 Finally, synchronize this directory upwards to Savannah:
 134
 135 rsync -n -e "ssh -1" -t -u -v -r *.pkg likewise@savannah.nongnu.org:/upload/lwip
 136
 137 This does a "dry run": no files are modified! After you have confirmed that
 138 this is what you intended to do, remove "-n" and actually synchronize for
 139 real. The release should now be available here:
 140
 141 http://savannah.nongnu.org/files/?group=lwip
 142
 143 ---
 144 Explanation of rsync options used:
 145
 146 -t: preserve file timestamps
 147 -u: do not overwrite existing files, unless they are older
 148 -v: be verbose (long format file attributes)
 149 -r: recurse into directories
 150 -n: dry-run, do not modify anything.
 151 ---
 152
 153 Additionally, you may post a news item on Savannah, like this:
 154
 155 A new 0.6.3 release is now available here:
 156 http://savannah.nongnu.org/files/?group=lwip&highlight=0.6.3
 157
 158 You will have to submit this via the user News interface, then approve
 159 this via the Administrator News interface.