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)
   Updated pip and setuptools, setuptools.__version__ -> '36.2.7'
   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
   Tried	
	 py -3.6 -m twine upload -r https://test.pypi.org -u user -p pwd dist/*
	No, failed. Changing the url to https://test.pypi.org/legacy/ , failed also.
	So, decayed to old method; remember that each upload will do a build so be patient.

	0. Have at hand the usr/pwd for both pypi and test.pypi
	
	1. set a c:\Users\user\.pypirc file with content
		[distutils]
		index-servers =
		  pypi
		  pypitest

		[pypi]
		repository=https://pypi.python.org/pypi
		username=not_the_real_user
		password=not_the_real_pwd

		[pypitest]
		repository=https://testpypi.python.org/pypi
		username=real_test_user
		password=real_test_pwd
   
    Notice for the test try I don't put the real credentials for pypi, only for pypitest
	
	2.  from the root of repo checkout, with the docs in position run
	
			py -3.6 setup.py sdist upload -r pypitest

		Fails; setting the pypitest URL to https://test.pypi.org/legacy/

		And trying again the same command

			py -3.6 setup.py sdist upload -r pypitest
			Server response (200): OK

		Check if it visible and looks good at https://test.pypi.org/project/cocos2d/
		Looks good. (search for cocos2d pointed to an older release)
		
	3. 	Now to the real upload
		Set the real pypi credentials in .pypirc and run
		
			py -3.6 setup.py sdist upload -r pypi
			200 OK

		Notice the last arg is different; also no 'legacy' was required here.

		Check if it visible and looks good at https://pypi.python.org/pypi/cocos2d
		Looks good. (search for cocos2d pointed to an older release)

	4. 	Download the file in that page, decompress, compare with repo; only some artifacts from the build will
	    show as missing files

	5. 	I deleted the .pypirc to not let cleartext credentials in sight.

8.  tagging the release 

	from the repo clone used to upload:

		- delete release artifacts, use git status to see what should be deleted
		
		- If some last moment change was not comited, commit now and push
		
		- run
			git tag release-0.6.5 -m "tagging release 0.6.5"
			git push --tags
			
		- lookup the last hash commit, edit the following line to meet your release
			git commit -a -m "tagged  fe6beb3 as release-0.6.5"
		  save file 
			
		- commit using the line just edited, push.