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 that.

 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 -3.6 ./tools/clean_pyc.py .
	   ]
       py -3.6 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. (WinMerge or Meld work fine 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 *)

	(*) note: while testing for the 0.6.5 release, while the pyglet in Pypi was 1.3rc1,
	    with py36 and venvs, the two instalations picked a different pyglet. The first,
		which I assume is using setuptools, installed 1.3rc1, the second, using pip,
		installed 1.2.4, the last stable pyglet in Pypi.
		Keep in mind this for releases where the pyglet version is critical and the
		one we want is not yet a stable release.
		
	(**) if using venvs, keep in mind that some dependencies will not be installed,
 	     namelly numpy, audio dll's, pillow. 
		
    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:\python36\Scripts
	   cd docgen
	   make clean
	   make html
       (resp Makefile clean && Makefile html in unix-land)
	   	   
    move the docs to be more discoverable
	   py -3.6 ../tools/copy_docs.py

    clean debris in docgen 
	   make clean
	   
   clean *.pyc's and build the package
	   cd ..
	   py -3.6 ./tools/clean_pyc.py .
	   py -3.6 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 (or virtualenv) replace
		py -3.6 -> python or python3
		make ->Makefile
	It should work with python 2.6, 2.7, 3.3+ , tested with 3.6
		
 6 Updating the website, currently python.cocos2d.org subdomain
   The current layout is
     doc/ ->  *needs update on release* directory with the html docs generated for cocos,
	 just delete the old contents and copy there the contents in doc/html from the release .zip 
    coco.png
    contribute.html -> not release related
    doc.html -> links into the doc dir, also links to video tutorials not release related
    download.html -> *needs update on release* download links, dependencies 
    favicon.ico -> favicon to show in the address toolbar 
    games.htm -> sample games, not release related
    grossini.png -> warn, maybe also used for iphone 
    index.html -> *needs update on release* the homepage, news and demo videos
    style.css
    tetrico.jpg

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

  When the contentents are ready to publish, sftp to host and sync to python.cocos2d.org .
   
 7 Updating PyPI page
   (2017 notes)
   In https://packaging.python.org/tutorials/distributing-packages/ they recomend to upload with twine, available from pypi
   Installed with pip, got twine 1.9.1
   
   py -3.6 -m twine upload -r https://test.pypi.org -u ccanepa -p TestPySpoakK87**pytn3 dist/*
   
   ---------------
  F:\dev\cocos2017>py -3.6 setup.py sdist upload -r pypitest
   
   
   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

in 2017
In https://packaging.python.org/tutorials/distributing-packages/ they recomend to use twine to upload to Pypi
 
	[distutils]
	index-servers=
		pypi
		testpypi

	[testpypi]
	repository: https://test.pypi.org/legacy/
	username: your-testpy-user
	password: your-testpy-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 to 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 ?
   

8.  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 )

    If a commit after the release was done, then add to the first line the hash of the
	commit used for the release
