How To Release.rtf
	
PLATFORMS:
	
Only OS X for now.

AUTHORS:
	
Allen Ingling		awi		Allen.Ingling@nyu.edu

DESCRIPTION:
	
 This document lists the steps to release a Psychtoolbox for OS X.

RELEASE STEPS: 

1. Either print this document of make a copy outside of the PsychSourceGL folder; In later steps, this file will be compressed into an archive and you will not have access to it.  

2. In subsequent steps, markup any changes to this document on the copy which you made in the previous step.  

3. Synchronize your local PsychSourceGL folder with the remote version on Mussell.  In subsequent steps, build the Psychtoolbox archive from the local version, not the remote version.    

4. The first step of "How to Add To Screen.rtf" is to make sure that you have the most recent version of Xcode.  Check developer.apple.com for the most recent version, make sure the PTB builds with it, and substitute in the most recent Xcode version number.  

5. Check the title and first paragraph of the file "Updated_for_MATLAB701.h" source documenation to see if named versions of dependencies are stated correctly.

6. Check the README.rtf document to be sure that versions and dates are stated correctly within.

7. If you added any new MATLAB functions, then update Contents.m files accordingly.

8.  Remove the ~ backup files from the Psychtoolbox folder.   

9. If you fixed any bugs, check the bugs listed on the OS X web page and remove them from the list.   

10. Check for absolute paths to Psychtoolbox source files and fix them.  Xcode sometimes reverts to absolute paths for unknown reasons.  One cause is renaming a file from within Xcode, that silently changes the file path to an absolute path.  The problem is worse than that though.  

Note that absolute paths to system files are fine because they are always found in the same place on every system.  It's only paths to Psychtoolbox source files which should be relative to project, so that paths do not break when relocating the Psychtoolbox source.

The HID Utilties headers and libraries used by the PsychHID Psychtoolbox target are special;  Unlike all other files used by the PsychHID Psychtoolbox project, they have no guaranteed relative or absolute location.  Our own  files have guaranteed relative positions because they are always in the same locations relative to the enclosing "PsychSourceGL" folder.  System libraries have guaranteed absolute positions, because Apple always puts them in the same place on all systems.   Apple's HID Utilities is neither a system library nor part of the Psychtoolbox, but instead another Xcode project which builds libraires used by the Psychtoolbox PsychHID project.  It has no pre-designated absolute or relative posistion.  You have to get it and put it in the right place for the PsychHID project to find it. Building the PsychHID target depends on you placing Apple's HID utilities project folder at the same level as the PsychSourceGL folder-  The PsychHID target uses project-relative references to header and library files within the HID Utilities folder.            
   
To detect and absolute paths to Psychtoolbox source files and replace them with relative paths: Close Xcode, relocate the PsychSourceGL folder to anywhere off the path which you have been using, open the project in Xcode and expand all of the tabs in Xcode's Groups & Files pane on the left.  Any files which Xcode can not find are displayed in red. Xcode can not find them because the files were specified using an absolute path which changed when you moved the folder.  Write down the names  of the files in red.  Close Xcode.  Relocate the Xcode folder to its original location.  Open the project. Get info on each of the files which were highlited in red. In the info box use the drop down menu to change the path specification method from "absolute" to "relative to project."  (If there are many, you can mulit-select and get info on the group.)  As explained in the previous paragraph, relative paths to HID utilities libraries and headers are an exception.  

11. Check the Psychtoolbox.org web site to find the version number of the last release.  

12. Increment the Psychtoolbox version number.  See the roadmap if one exists.  Otherwise, See "help PsychToolboxVersion" for the meaning for version number fields. 

13. Change  the version number in the Psychtoolbox file "Psychtoolbox/Contents.m" file.

14. Change the date in the Psychtoolbox file "Psychtoolbox/Contents.m" file.

15. Change the version set in in constants PSYCHTOOLBOX_MAJOR_VERSION, PSYCHTOOLBOX_MINOR_VERSION  and PSYCHTOOLBOX_POINT_VERSION in the source file "PsychVersioning.h" to  indicated the same value set in the Contents.m file.  You don't need to change the date in the source code, the project automatically inserts that using a date macro.  

16. Clean all targets.  This forces a complete rebuild of each binary in the next step.  

17. Build all targets.  This replaces all binaries in the Psychtoolbox folder and the Xcode projects.

18. Clean all targets.  This leaves the binaries in the Psychtoolbox but removes those from the Xcode projects, reducing its size for distribution.

19. Remove GetChar.mexmac from the Psychtoolbox folder.  It causes MATLAB to crash now. 

20. Copy the Psychtoolbox folder out of the source folder and post it to the web site.

21. Re-evaluate and revise the roadmap on the osx.html page.  

22. On the osx.html page in the "Roadmap" section is a sentence such as "The current OS X Psychtoolbox is version 1.0.42, released on 27 January 2005.  Update that sentence.

23. Update the "news" box on the home page (index.hmtl) to state the new release version.  

24. On the osx.html page in the "Known Bugs" update the list by removing any bugs fixed by the current release. 

25. On the osx.hml page in the "Changes" section update the list to inlude changes for the new release.       

26. Post the Psychtoolbox source folder to the web site. 

27. Send out a notice to the forum.  

28. If it's major release, also send out a notice to the mailing list. 

29. For the next release ahead, replace the old copy of this file in the PsychSourceGL folder with the new copy which you made (step 1) and modified (step 2).  

30 Synch the new Psychtoolbox folder with the master copy on mussell.  

HISTORY:

7/24/04		awi		
Created.  

7/27/04		awi		
Added note about checking for absolute and paths in Xcode and changing them to relative paths.

11/3/04		awi		
Clean up.  Fill in more details.

11/9/04		awi		
Added steps to update dependency versions in documentation if needed.

11/18/04	awi		
Integer numbering scheme.  Amended announce step to include conditional announcment to mailing list.  Improved documentation of how to purge absolute paths.  Added step to check Contents. 

12/1/04		awi		
Added steps to update osx.html.

1/8/05	awi
Cosmetic.  Added step to check Xcode version number given in "How to Add To Screen.rtf".

1/27/05 awi
Added steps at the beginning to synchronize and copy out this document and at the end to merge markups to this file bac into the master .  Moved HISTORY section to the bottom.  More notes about web site updates.

4/7/05	awi
Added step to remove the ~ files, explained that HID utilities exception in detecting absolute paths, added step to remove GetChar.mexmac, added step to re-evaluate roadmap. 

*/