HOW TO USE THE SOURCE REPOSITORY
--------------------------------

Content
=======

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 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 Git server
=========================================================
by Viktor Szakats

 1. Read the Harbour README.md, 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 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.
 2. You'll need an Git client for your platform.
 3. Do a 'git clone' to get your own local development Git repository.

1.2 Here's how to upload your changes to the Git server
=======================================================
by Viktor Szakats

 1. Make the changes in the source
 2. Do a 'git pull'
 3. Resolve any conflicts
 4. Run 'hbrun bin/commit' to check any commit pre-checks
    and to create new ChangeLog.txt entry template
 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

NOTE:
   - Run once 'git config --global core.autocrlf true' on Windows
   - Run once 'git config --global core.autocrlf input' on *nix

1.3 Here's how to format your ChangeLog.txt entries
===================================================
by Viktor Szakats

- Use 'hbrun bin/commit' to create a new ChangeLog entry

- Add description below each group of changed files.
  Describe what you've changed, the reasons, and other comments
  and explanations you find useful.

- To refer to a commit, simply include the commit hash in the
  text. If you refer to a commit in another fork,
  include the whole (GitHub) URL of the commit.

- To refer to an issue, include issue number prefixed with
  a # character. If you include the word "fixes", "fixed"
  or similar, the issue will automatically be closed.
  See more here:
     https://help.github.com/articles/writing-on-github#references

- In case of incompatible changes visible on the user-level,
  add the word 'INCOMPATIBLE' to the text.

- In case some translatable strings have changed,
  add the word '[TRANSLATION]' to the text.

- Mark comments suggesting further fixes with 'FIXME: ', 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.

- Leave an empty line after the body.

1.4 Here's how to use the Git server in read-only mode
======================================================

   git clone https://github.com/harbour/core.git harbour-core

1.5 Things to do to avoid damaging the Git repository
=====================================================
by David G. Holm

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 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 '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. 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 'git pull' and other changes
   have been committed by others, then ChangeLog.txt will have conflicts.
   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-2014 Viktor Szakats (vszakats.net/harbour)
  Licensed under Creative Commons Attribution-ShareAlike 4.0:
  https://creativecommons.org/licenses/by-sa/4.0/
  See LICENSE.txt. ]