After a release, please update this document if any change was needed.

 0 Update the copyright/license header in all files under cocos/ and tools/skeleton/
   The script tools/change_license.py is used for thet.

 1 Checking that the pypi page has proper reST
   To check for reST conformance, somewhere (distutils ? pypi ?) the command
	$ python setup.py --long-description | rst2html.py > output.html
   was suggested. The translation to windows is
        setup.py --long-description | rst2html.py > output.html
   That not worked for me in windows with python 2.6,  I used
	setup.py --long-description  >pypy.txt
	rst2html.py  --traceback  pypy.txt > output.html

 2 Building the docs
   Have sphinx >= 1.3.1 and dependencies instaled, build by:
		cd working_copy/docgen
		make clean
		make html

   (replace make with Makefile in unix-like OSes)

   Docs will be found at working_copy/docgen/_build/html 

   Check for errors and warnings at working_copy/docgen/warnings.log	

   Work the docstrings to reduce errors and warnings.

   Also, look some random pages in the generated html to see if there are any
   surprises.

 3 Building the package (without the docs)
   Have a modern setuptools installed, for cocos 0.6.2 setuptools 12.2 was used
   to build the release
   Cmds to build:
       git clone https://github.com/los-cocos/cocos.git cocos2d-python
	   or, if using ssh,
       git clone git@github.com:los-cocos/cocos.git cocos2d-python
       cd cocos2d-python
	   [if needed eliminate *.pyc's with
			py -2.7 ./tools/clean_pyc.py .
	   ]
       py -2.7 setup.py sdist >../sdist.log
       [ the generated package will be in cocos-build/dist ]
	
	Verify all is included by decompressing the generated .gz or .zip and comparing with a diff tool cocos2d_python and the decompressed one. (used WinMerge in windows)
	
 4 Installing the new package for test
   Preparation:
       backup easy-install.pth -> easy-install._pth
       hide any cocos and pyglet visible from python, this depends on how you
       handle multiple version for packages ( .pth ? , PYTHONPATH ?, ...)
       check that import pyglet and import cocos fails with
         ImportError: No module named [pyglet, cocos]

    Install:
        mode1:
			cd cocos2d-clone
			py -2.7 setup.py install >install.log
			(verify the install)
			
		mode2:
			cd cocos2d-clone
			pip install .
			(verify the install)

    Cleanup (after tests are done):
        Delete additions in site-package, restore easy-install.pth, check that
        import pyglet and import cocos fails as before, restore your normal
        machinery to handle multiple package versions for cocos and pyglet
		
	[if posible, test also an instalation in a python without sdl dependencies,
	it should all work except the audio tests (currently only one)]
	
  5 Final build including docs
       clone the repo with 
       git clone https://github.com/los-cocos/cocos.git cocos2d-python
	   or, if using ssh,
       git clone git@github.com:los-cocos/cocos.git cocos2d-python

	move into the clone
       cd cocos2d-python
       
	building the docs
	   pyglet must be installed for this to work
	   set the envar SPHINXDIR to the dir where sphinx scripts can be found  
	   set SPHINXDIR=c:\python27\Scripts
	   cd docgen
	   make clean
	   make html
       (resp Makefile clean && Makefile html in unix-land)
	   	   
    move the docs to be more discoverable
	   py -2.7 ../tools/copy_docs.py

    clean debris in docgen 
	   make clean
	   
   clean *.pyc's and build the package
	   cd ..
	   py -2.7 ./tools/clean_pyc.py .
	   py -2.7 setup.py sdist
      [ the generated package will be in cocos_build\dist , docs will show at doc/html in the package archive ]
	  
	In unix like replace
		py -2.7 -> python
		make ->Makefile
	It should work with python 2.6, 2.7, 3.3+ , tested with 2.7 and 3.3
		
 6 Updating cocos2d.org site
   the ftp URL points to a general directory with things not to touch;
   we are interested in a subset of www directory (which also holds other
   things ).
   Listing only the cocos related files:
   www
    doc -> 	directory with the html docs generated for cocos, update on release
			after building the docs, upload the contents of doc/html to this directory (www/doc)

    coco.png
    contribute.html -> not release related
    doc.html -> links into the doc dir, also links to video tutorials not release related
    download.html -> download links, dependencies, *needs update on release*
    favicon.ico -> 0 sized atm
    games.htm -> sample games, not release related
    grossini.png -> warn, maybe also used for iphone 
    index.html -> the homepage, news and demo videos, *needs update on release*
    style.css
    tetrico.jpg

   The files are maintained in the repo https://github.com/los-cocos/cocos-site

   The doc directory is not stored because is generated by the doc builder.
   
   2014+: talk to the contact in cocos2d.org so him/her updates the site from the github
   site repo plus the pypi zip (for the docs) 
 
 6 Updating PyPI page
   Albeit pypi home page tells to use "python setup.py upload" to upload the
   package, this gave me 401: You must be identified to edit package information

   A search suggested

	python setup.py register sdist upload

   which should build, request user:pwd interactively and upload
   In windows xp sp3 with python 2.6 that failed: it request the user,
   you fill it, it request pwd, it wont accept characters.
   You must ctrl-c or wait a timeout.

   Another search suggested using the same line but creating a .pypirc file
   in your HOME directory with the contents
    [pypirc]
    servers = pypi
    [server-login]
    username:pypi_user
    password:pypi_pwd

   Just in case, I stored that with unix line endings.
   That worked for me.
   
   For windows users, you can see where your HOME directory is by typing
     set homepath
   in a cmd console (usually Documents and Settings\<user>)

   Probably more info at:
       http://packages.python.org/an_example_pypi_project/setuptools.html#intermezzo-pypirc-file-and-gpg

	year 2015: the .pypirc format seems to have changed, at least for what can be seen at
	https://packaging.python.org/en/latest/distributing.html#uploading-your-project-to-pypi
	or
	https://wiki.python.org/moin/TestPyPI 

	
   Theres a test site parallel pypi, https://testpypi.python.org/pypi , which can
   be handy to test the real display of package page and other pypi related things, see
   https://wiki.python.org/moin/TestPyPI
   
   warn: with the recomended .pypirc (login info for both pypi and testpypi)
   python setup.py register sdist upload -r https://testpypi.python.org/pypi
   wrote both to the test and the real site; in the real only the package page was
   updated (no download), also the pakage upload terminated with error, so it should
   be better to delete / modify the real login info when testing
   Maybe the register part was directed to the real pypi ?
   

7.  tagging the release 

	from a working copy, in the checkout of master that reflects the state at release do
		git tag release-0.6.3 -m "tagging release 0.6.3"
		git push --tags

	( remember to change the version in the example if doing copy & paste )
