diff --git a/ChangeLog.txt b/ChangeLog.txt index 4deed05763..1c63218b4e 100644 --- a/ChangeLog.txt +++ b/ChangeLog.txt @@ -10,6 +10,10 @@ * Change, ! Fix, % Optimization, + Addition, - Removal, ; Comment */ +2013-03-18 00:01 UTC+0100 Viktor Szakats (harbour syenar.net) + * doc/howtorep.txt + * updated for Git + 2013-03-17 23:04 UTC+0100 Viktor Szakats (harbour syenar.net) * contrib/hbcairo/image.c ! fixed to always define .prg level CAIRO_IMAGE_SURFACE_CREATE() diff --git a/doc/howtorep.txt b/doc/howtorep.txt index 0f994ac7b8..805f6023f1 100644 --- a/doc/howtorep.txt +++ b/doc/howtorep.txt @@ -5,172 +5,112 @@ HOW TO USE THE SOURCE REPOSITORY Content ======= -1.1 Here's how to prepare for uploading to the SVN server -1.2 Here's how to upload your changes to the SVN server +1.1 Here's how to prepare for uploading to the Git server +1.2 Here's how to upload your changes to the Git server 1.3 Here's how to format your ChangeLog entries -1.4 Here's how to use the SVN server in anonymous read-only mode -1.5 Things to do to avoid damaging the SourceForge SVN tree -1.6 How to add SVN ID to new files +1.4 Here's how to use the Git server in anonymous read-only mode +1.5 Things to do to avoid damaging the Git repository -1.1 Here's how to prepare for uploading to the SVN server +1.1 Here's how to prepare for uploading to the Git server ========================================================= by Viktor Szakats 1) Read the Harbour README.txt, monitor the development mailing list, consult with the developers, make contributions. This way your chances are high to get a R/W access to the repository. - 2) Before uploading anything you'll need Developer (R/W) status for the - Harbour SVN server. To get this please make a request on the list, - or contact the Harbour Administrators. Note that getting Developer - status is not an automatic process. - 3) You'll need an SVN client for your platform. - 4) Do a complete checkout to get the fresh source tree. + 2) Before uploading anything you'll need push permission for the + Harbour Git server. To get this please make a request on the development + list. Note that getting Developer status is not an automatic process. + 3) You'll need an Git client for your platform. + 4) Do a 'git clone' to get your own local development Git repository. -1.2 Here's how to upload your changes to the SVN server +1.2 Here's how to upload your changes to the Git server ======================================================= by Viktor Szakats - 1) Do the changes in the source, and in parallel modify ChangeLog.txt - 2) Go online (if needed) - 3) svn update - 4) Resolve all conflicts - 5) Copy the last ChangeLog.txt entry to the clipboard - 6) svn commit --editor-cmd notepad.exe --username sfuser - Change notepad.exe to the editor of your choice and platform. - Change "sfuser" to your sf.net username. - 7) The SVN pops up a window with the changed filenames - 8) Check if all the changed filenames are referred in the ChangeLog.txt entry, - if not, make the corrections and start again - 9) Paste the ChangeLog.txt entry header to the SVN window, save, exit -10) SVN is now uploading, - if there are any errors, make the corrections and start again -11) Always check if the upload session ended without errors. -12) Go offline (if needed) - -alternative method: -by Ryszard Glab - - 1) Do the changes in the source - 2) Run 'svn update' redirecting the output into a file - (for example: "svn update -d >.log" - 3) Resolve all conflicts, run SVN update again (see point 2), recompile - all sources, fix all errors - 4) Run 'svn status' redirecting the output into a file - (for example: "svn status >.log" - 5) Copy all names of modifed, added or deleted files (files marked with - 'M', 'A' or 'D' flag) from update log into the ChangeLog.txt - 6) Write necessary comments in the ChangeLog.txt - 7) Save all your changes from ChangeLog.txt into a file - 8) Run 'svn update' again - 9) Commit changes running: - svn commit -F file_with_saved_ChangeLog_changes --username sfuser + 1) Make the changes in the source + 2) Do a 'git pull' + 3) Resolve any conflicts + 4) Run 'hbrun bin/commit' to create new ChangeLog.txt entry + with timestamp and list of modified files + 5) Edit ChangeLog.txt with a text editor (do not use Notepad.exe) + 6) Copy the last ChangeLog.txt entry to the clipboard + If it's a single atomic change, it's better to copy only + the description itself without the entry header and list + of files. + 7) Do a 'git commit [-a]' + 8) Paste clipboard content to the text editor that popped up + 9) Save and exit in editor +10) Git is now committing +11) Do a 'git push' to publish your changes online to the + master repository Important notes: - 1) *Always* add a ChangeLog.txt entry when committing to the SVN. - 2) When adding a new file to the SVN, always use lower case 8.3 - filenames (*), add a SVN ID header to the file, don't use tabs - in the file, end the file with a newline char. - Possibly consult other Developers about the new filename and file - placement. - Add the new filename to the related makefiles. - (*) There are some exceptions: ChangeLog.*, Makefile, COPYING.txt, - README.txt. + 1) *Always* add a ChangeLog.txt entry when committing. + 2) When adding a new file to the repository, always use lower case 8.3 + filenames, do not use tabs, trailing spaces, BOM and EOF markers + in the file, end the file with a newline. 1.3 Here's how to format your ChangeLog.txt entries =================================================== by Viktor Szakats -- Always add new entries to the top of the ChangeLog.txt +- Use 'hbrun bin/commit' to create a new ChangeLog entry -- Add an entry header using this format: - YYYY-MM-DD HH:MM UTC[-|+]hhmm Your Full Name +- Add description below each group of changed files. + Describe what you've changed, the reasons, and other comments + and explanations you find useful. - For example: - 2011-05-27 23:12 UTC+0100 Viktor Szakats (harbour syenar.net) +- In case of incompatible changes visible on the user-level, + add the word 'INCOMPATIBLE' to the text. -- Add a entry body which lists all filenames changed, all of - them with full path spec. Mention the name of the changed function or - macro. Describe what you've changed, the reasons, and other comments - and explanations you find useful. If the change needs some related work - to be done by someone else (documentation, makefile), make a clear note - about this. - Group the related changes into logical sections separated by empty lines. - - Sample: - - * dir/filenam1.txt - + dir/filenam2.txt - - dir/filenam3.txt - * Change - ! Fix - % Optimization - + Addition - - Removal - ; Comment - -- Best is to use commit.hb script to add new entry: - $ hbrun bin/commit.hb - Then add the change descriptions. - -- In case of incompatible changes, add the word 'INCOMPATIBLE' to - the text. - -- Mark comments suggesting further fixes with '[TOFIX]', further - todos as '[TODO]', and update these to '[DONE]' when implemented. +- Mark comments suggesting further fixes with 'TOFIX: ', further + todos as 'TODO: ', and update these to '[DONE]' when implemented. - Mark changes to merge with different branch as '[TOMERGE x.0]'. Changes these to '[MERGED x.0]' when merge is completed. -- Mark changes causing user-level incompatibility with '[INCOMPAT]' +- Leave an empty line after the body. -- Do not use tabs and non-ASCII chars. Remove trailing spaces. +- Do not use tabs, trailing spaces, BOM and EOF markers + in the file, end the file with a newline. -- Leave an empty line between the header and body and one after the body. +1.4 Here's how to use the Git server in read-only mode +====================================================== -- Do not add unicode BOM to the file + git clone git://github.com/harbour/core.git harbour -- Do not use tabs - -1.4 Here's how to use the SVN server in anonymous read-only mode -================================================================ - -Please read the following FAQ entry: - http://harbour-project.org/faq/harbour25.html - -1.5 Things to do to avoid damaging the SourceForge SVN tree -=========================================================== +1.5 Things to do to avoid damaging the Git repository +===================================================== by David G. Holm -1) Always do your Harbour development using your local SVN tree. Do not - do your development outside your local SVN tree and then copy your - changes into your local SVN tree to commit them, because that leads +1) Always do your Harbour development using your local source tree. Do not + do your development outside your local source tree and then copy your + changes into your local source tree to commit them, because that leads easily to accidentally overwriting changes made by others, because you didn't notice that a module that you were also working on was changed by someone else. By always doing Harbour development using - your local SVN tree, changes made by others will be merged with your + your local source tree, changes made by others will be merged with your changes and you only need to recompile and retest before committing. -2) Always run 'SVN update' from the 'harbour' directory before you run - 'svn commit'. Ideally, you should redirect the output from the update - to a file and look at the results to confirm that you are ready to do - a commit. Any files marked M, A or D are files that you have modified - or are adding or deleting. Confirm that you have comments for all of - them in your ChangeLog.txt entry. If you see many modules marked P or U, - then you need to recompile and retest before you commit your changes. +2) Always run 'git pull' from the 'harbour' directory before you run + 'git commit'. Run 'hbmk2 bin/commit' before committing, which will + create a new entry at the top of ChangeLog.txt, which you can then + edit with the description of changes. If you see any conflicts reported in the update output, then you need - to resolve them before committing. SVN is generally good at merging + to resolve them before committing. Git is generally good at merging changes, so you probably won't see conflicts very often, but if you - edit the ChangeLog.txt before you run 'svn update' and other changes + edit the ChangeLog.txt before you run 'git pull' and other changes have been committed by others, then ChangeLog.txt will have conflicts. - To resolve those conflicts, simply remove the conflict markers. What + To resolve those conflicts, you need to resolve the conflict. What I do to avoid conflicts to ChangeLog.txt is to record my changes in changes.txt and then copy them into ChangeLog.txt between the update and the commit. -[ Copyright (c) 1999-2012 Viktor Szakats (harbour syenar.net) +[ Copyright (c) 1999-2013 Viktor Szakats (harbour syenar.net) Licensed under Creative Commons Attribution-ShareAlike 3.0: http://creativecommons.org/licenses/by-sa/3.0/ See COPYING.txt. ]