Skip to content

Latest commit

 

History

History
189 lines (169 loc) · 11.2 KB

CONTRIBUTING.md

File metadata and controls

189 lines (169 loc) · 11.2 KB
Raw

Contributing to this fork of Harbour

Table of Contents

  1. How to Share
  2. How to Get Involved
  3. Troubleshooting

How to Share

Share by linking to this project from your forum, blog or Twitter. Link to commits, issues or source files, or whatever else you find worthy to pass to someone. This is the easiest, most useful and self-updating way of referring to this project. It's also the best form of crediting and appreciating this work without donating or participating directly.

Examples:

How to Get Involved

  • You can give feedback/suggestions by submitting an issue.

  • Submit a patch:

    1. Fork the repository
    2. Create a branch: git switch -c mypatch or git checkout -b mypatch (for Git 2.22.x and earlier)
    3. Do commit pre-check and new log entry: hbrun bin/commit
    4. Commit your changes: git commit -am "Add this feature to that module"
    5. Push to the branch: git push origin mypatch
    6. Open a Pull Request

  • Make sure to use the same coding/formatting style as you find in the files you're updating. The easiest way to achieve this is to use these commands to format the sources (use this with care - most sources are well-formatted, so make sure to only apply it to newly added or updated code sections)

      $ uncrustify -c <harbour-dir>/bin/harbour.ucf <source{.c|.h}>
  $ <harbour-dir>/bin/hbformat <source{.prg|.hb|.ch}>

  • Text editor setting for Harbour files

    • Encoding is either 7-bit ASCII or UTF-8, without BOM
    • Use spaces (U+0020), never tabs or non-breaking spaces
    • Remove trailing spaces from lines
    • Keep one (not zero or multiple) newline at the end of file
    • Use platform native newline (CRLF or LF)

  • In the rare case you need to send something large (> 100 kB), use this free service.

  • See this good guideline on how to contribute: https://github.com/necolas/issue-guidelines/blob/master/CONTRIBUTING.md

  • And these:

  • You can also participate in localization:
    Localization Status

  • If looking for known pending issues to work on, look for TODO and FIXME markers in the source code/ChangeLog or see this list of issues that need further input/contribution:

Troubleshooting

Evaluate these points before reporting an issue:

  1. Make sure to have carefully read this document.

  2. Make sure to do a make clean before doing a build after refreshing the sources.

  3. If that still fails, make sure to install fresh source tree in a new local directory and start over. See How to Get for instructions to get the source. In case you installed Harbour into system locations (this used to be the case with some *nix users, albeit mostly unnecessarily or wrongly - e.g. for unstable versions), you will need to remember cleaning off Harbour from these locations, too. Hint: Never install unstable Harbour versions to system locations.

  4. If you are doing a cross-build, make sure to have rebuilt the native Harbour executables for your host platform. See HB_HOST_BIN build messages to find their location.

  5. Keep your PATH clean from old, mixed compiler tools or other Harbour versions when building Harbour. The surest way to achieve this is to leave only the C compiler directory in PATH:

    set PATH=C:\<c-compiler-bin-dir>

    If you use Harbour official binary distro on Windows, even above is unnecessary, so avoid it.

  6. Remove all old, unnecessary environment variables (for both Harbour and C compiler) from your environment. Also remove any custom settings for your C compiler. Use only those documented in this file.

  7. Remove any Harbour build settings documented in Build Options.

  8. Do no or only minor updates at once to the examples included in Build Examples. If it doesn't work, fall back to documented examples as is.

  9. If everything fails and you are to report a build problem to Harbour developers, make sure to include your OS version/language/CPU architecture, Harbour revision, C compiler name/release and version, environment variables and verbose log output containing both STDERR and STDOUT in one combined stream (use make > log.txt 2>&1). Enable verbose mode using HB_BUILD_VERBOSE=yes and do not enable multi-threaded (parallel) build. Configure your tools to output English language messages using HB_LANG=en and LANG=en_GB.UTF-8. Complete log output is rarely necessary, but make sure to include the top of the output (lines starting with !) and the area where problematic behavior occurred first. Make sure to not only include a link failure or a make tool failure, as it's most often not enough information. Compress your log using zip if it is larger than 25 kB (use the extension .zip). With these, you have much better chance to get useful or any response.

  10. Do not alter the directory layout and files in Harbour and 3rd party packages and tools (including C compilers).

  11. If you are to report a build problem with a Harbour application, all the above points apply, plus make sure to use hbmk2 with the -trace command-line option and redirect its output to a file (see above how). Also include your full command-line and any referenced build script in your report. It is good idea to first remove all manual references to Harbour core components from make-files and custom environment. E.g. it's common mistake to add C compiler header and/or lib dirs, Harbour core header and/or lib dirs, built-in constants to make-files or environment. No such thing is necessary as these are automatically handled by hbmk2. In other words: start simple and don't be over-busy with fine-tuning your configuration. If you need to, the problem is most probably elsewhere. It's also good idea to try with the latest Harbour revision or Harbour's mainline branch first.

  12. If you are to report a problem with Harbour itself, include self-contained, minimal source code example. Do not use xhb contrib library (including hbcompat.ch), nor any 3rd party Harbour libraries. The example should reproduce the problem using the latest Harbour revision (with no local commits or pending local updates) at the time of the report. Do not post links to executables and other binary files. If your source contains non-ASCII and non-UTF-8 national, accented, special chars, make sure to mark the codepage/encoding used and use Chr()/hb_BCode() calls to form the strings. Use UTF-8 if possible. Notice that core developers are likely to run code examples as hbrun scripts for testing, so it's a good idea to make them work this way.
    Also make sure not to report multiple issues under a single GitHub Issue.

  13. Please do not report warnings or bugs — except build errors — in 3rd party components hosted inside the Harbour source tree. You can recognize these by their source path, which always contain a subdirectory named /3rd/. Report these directly to the maintainer of the respective component instead.

  14. If your example or report contains human readable text, use English only.

  15. If your example involves compatibility components, make sure to test it against original implementation (e.g. legacy Cl*pper core language elements against real CA-Cl*pper 5.2e or 5.3b, or hbct functions against CT3 library, etc.) Notice that Harbour is Cl*pper Summer '87 compatible exactly as much as Cl*pper 5.2e/5.3b is, meaning: almost, but not completely. For tests with Cl*pper, use this free, open-source MS-DOS emulator (requires Windows/Wine).

This document Copyright © 2009–present Viktor Szakats
Creative Commons Attribution-ShareAlike 4.0