attachment:stella-talk.txt of days64.5

   1 |Sage development in a (big) nutshell| 
   2 |------------------------------------|
   3 
   4 Fact: sage is BIG!
   5 
   6 	The usual install takes nearly 6G and there are hundreds of people
   7 	contributing to its development.
   8 
   9 Need tools to keep development under control
  10 
  11 	* *Git*  a (very good) Version Control System
  12 	* *Trac* a web based issue tracker
  13 
  14 
  15 |GIT - the stupid content tracker|
  16 |--------------------------------|
  17 
  18 - What is it for?
  19 
  20 	In layman terms it keeps track of all the different versions of your
  21 	files (including history and tests) and allows you to jump in between them.
  22 	
  23 	It lets you share your files with other authors and keeps all the
  24 	modifications distinct and traceable
  25 
  26 	It is used in the development of many pieces of software 
  27 
  28 	Works well with all text files: try it to maintain your LaTeX projects!!
  29 	
  30 - How does it work? (really abridged version)
  31 	
  32 	The versions of your files are organized in a tree structure
  33 
  34 		Nodes are called *commits*
  35 
  36 		Each node belong to a *branch*
  37 		
  38 		The current commit is called *HEAD*
  39 
  40 	- Example:
  41 
  42 	$ cd /tmp
  43 	$ mkdir git-example
  44 	$ cd git-example
  45 	$ git init
  46 	Initialized empty Git repository in /tmp/git-example/.git/
  47 	$ git status
  48 	On branch master
  49 
  50 	Initial commit
  51 
  52 	nothing to commit (create/copy files and use "git add" to track)
  53 	$ echo "Some text" > a_file
  54 	$ git status
  55 	On branch master
  56 
  57 	Initial commit
  58 	
  59 	Untracked files:
  60 	  (use "git add <file>..." to include in what will be committed)
  61 	
  62 	        a_file
  63 	
  64 	nothing added to commit but untracked files present (use "git add" to track)
  65 	
  66 	$ git add a_file
  67 	$ git status 
  68 	On branch master
  69 
  70 	Initial commit
  71 
  72 	Changes to be committed:
  73 	  (use "git rm --cached <file>..." to unstage)
  74 
  75         	new file:   a_file
  76 
  77 	$ git commit -m "This is the first commit (lets call it A)"
  78 	[master (root-commit) 9757e8b] This is the first commit (lets call it A)
  79 	 1 file changed, 1 insertion(+)
  80  	 create mode 100644 a_file
  81 
  82 	The situation righ now is this
  83 	
  84 		master ---- *A* --
  85 
  86 	$ echo "Some more text" >> a_file
  87 	$ echo "Even more text" > another_file
  88 	$ git status
  89 	On branch master
  90 	Changes not staged for commit:
  91 	  (use "git add <file>..." to update what will be committed)
  92 	  (use "git checkout -- <file>..." to discard changes in working directory)
  93 	
  94 	        modified:   a_file
  95 	
  96 	Untracked files:
  97 	  (use "git add <file>..." to include in what will be committed)
  98 	
  99 	        another_file
 100 	
 101 	no changes added to commit (use "git add" and/or "git commit -a")
 102 	
 103 	$ git add a_file another_file
 104 	$ git commit -m "Second commit (This is B)"
 105 	[master 2da3dee] Second commit (This is B)
 106 	 2 files changed, 2 insertions(+)
 107 	 create mode 100644 another_file
 108 
 109 	Now the situation is this
 110 		
 111 		master ---- A ---- *B* --
 112 
 113 	$ git checkout -b another_branch
 114 	Switched to a new branch 'another_branch'
 115 	$ echo "Third text" >> a_file
 116 	$ git commit -a -m "Third commit (This is C)"
 117 	[another_branch 212e815] Third commit (This is C)
 118 	 1 file changed, 1 insertion(+)
 119 
 120 	Now the situation is
 121 
 122 		master ---- A ---- B
 123 				    \
 124 		another_branch	     *C* --
 125 
 126 	$ echo  "Once more" >> a_file
 127 	$ git commit -a -m "This commit is D"
 128 	[another_branch 5073aeb] This commit is D
 129 	 1 file changed, 1 insertion(+)
 130 
 131 	Now the situation is
 132 
 133 		master ---- A ---- B 
 134 				    \
 135 		another_branch	     C ---- *D* --
 136 
 137 	$ git checkout master
 138 	$ echo "Yet some more text" >> another_file
 139 	$ git commit -a -m "This commit is E"
 140 	[master b6c0727] This commit is E
 141 	 1 file changed, 1 insertion(+)
 142 
 143 	Now the situation is
 144 
 145 		master ---- A ---- B ---- *E* --
 146 				    \
 147 		another_branch	     C ---- D
 148 
 149 	
 150 	$ git merge another_branch
 151 	Merge made by the 'recursive' strategy.
 152 	 a_file | 2 ++
 153 	 1 file changed, 2 insertions(+)
 154 	
 155 	
 156 	Finally the situation is
 157 
 158 		master ---- A ---- B ---- E ---- *F* --
 159 				    \		 /
 160 		another_branch	     C ---- D --
 161 
 162 		
 163 
 164 |Trac Server|
 165 |-----------|
 166 - What is it for?
 167 	
 168 	It is used to centralize and organize sage development
 169 
 170 	It provides:
 171 		
 172 		bug tracking
 173 		
 174 		new feature development
 175 
 176 		peer review
 177 
 178 - How does it work?
 179 	
 180 	Each task (bug report, new feature, etc) is assigned a *ticket*
 181 
 182 	Each ticket is reviewed before being accepted into sage 
 183 
 184 
 185 - How do I get an account?
 186 	  
 187 	Write an e-mail to *[email protected]* containing:
 188 	
 189 		your full name
 190 		preferred username
 191 		contact email
 192 		the reason for needing a trac account
 193 
 194 - How do I set up trac to know my computer?
 195 
 196 	- instal git-trac (not really needed but makes life easyer)
 197 	$ git clone https://github.com/sagemath/git-trac-command.git
 198 	$ cd git-trac-command
 199 	$ sudo python setup.py install
 200 	
 201 	- setup sage
 202 	$ cd /path/to/your/sage/install
 203 	$ git trac config --user USERNAME --pass 'PASSWORD'
 204 
 205 	- upload your SSH public key to the trac server:
 206 
 207 	$ ssh-keygen
 208 
 209 	Go to http://trac.sagemath.org
 210 	Log in with your trac username/password
 211 	Click on "Preferences"
 212 	Go to the "SSH Keys" tab
 213 	Paste the content of your public key file (e.g. ~/.ssh/id_rsa.pub)
 214 	Click on "Save changes"
 215 
 216 	- test it out
 217 
 218 	$ ssh [email protected] info
 219 
 220 
 221 |Working example|
 222 |---------------|
 223 
 224 - CluserSeed does not know how to compute d-vectors
 225 
 226 	sage: B = matrix([[0,-1],[1,0]])
 227 	sage: S = ClusterSeed(B)
 228 
 229 	sage: S?
 230 
 231 	- Find out where it is defined from  "String form"
 232 
 233 	- Have a look at the file
 234 
 235 	$ vim src/sage/combinat/cluster_algebra_quiver/cluster_seed.py
 236 
 237 	- Create new branch and a new ticket
 238 
 239 	$ git trac create "Add d-vectors"
 240 	
 241 	- start doing edits
 242 
 243 	$ vim src/sage/combinat/cluster_algebra_quiver/cluster_seed.py
 244 
 245 	- attach file to keep track of results (caveat: this may give problems
 246 	  when loading modules or doing comparisons)
 247 	
 248 	sage: cd /opt/sage/src/sage/combinat/cluster_algebra_quiver/
 249 	sage: %attach cluster_seed.py
 250 
 251 	607G 
 252 	:read ~/sage-days/code-1.py
 253 
 254 	- Test 
 255 
 256 	add documentation
 257 	:read ~/sage-days/code-1.5.py
 258 
 259 	- Save and commit
 260 
 261 	$ git commit -a -m "Add d-vector to ClusterSeed"
 262 	
 263 	- TEST IT
 264 
 265 	$ sage -b -t src/sage/combinat/cluster_algebra_quiver/cluster_seed.py
 266 
 267 	- Push changes to trac server
 268 
 269 	$ git trac push
 270 
 271 	- Play with ticket
 272 	
 273 	$ git trac browse
 274 
 275 	- More edits
 276 	
 277 	$ vim src/sage/combinat/cluster_algebra_quiver/cluster_seed.py
 278 
 279 	625G
 280 	:read ~/sage-days/code-2.py
 281 
 282 	$ git commit -a -m "Add d-matrix to ClusterSeed"
 283 	$ sage -b -t src/sage/combinat/cluster_algebra_quiver/cluster_seed.py
 284 	$ git trac push
 285 	
 286 	- Open it up for review
 287 	$ git trac browse
 288 
 289 	-------------------------------------------------------------
 290 	$ git checkout develop
 291 
 292 	- Review
 293 
 294 	$ git trac checkout #ticket