path: root/BACKPORTING

Overview
========

The LongTerm3 branch gets nearly all of its updates from default via
backporting. The process is simple:

  hg update LongTerm3
  hg graft -e [changeset]

This grafts (or cherry-picks) [changeset] from default into LongTerm3. The '-e'
option allows for editing the commit message. Backported commit messages usually
have the form:

  Backport: [original commit message]

  Backport of [revision]:[changeset].

Any backport-specific additions, modifications, or deletions from the original
changeset should be mentioned in the new message.

Note: the '-e' option also gives you a chance to compile and/or test any adverse
effects produced by the graft prior to commit. Any changes made to files before
committing will reflect in the final graft.

In order to back out of a graft:

  hg rollback
  hg revert --all [--no-backup]

This can only be done ONCE, and affects the most recent graft, so make sure you
test any questionable grafts first before attempting another one.

Testing Backports
=================

Backporting a change is one thing, but ensuring the backport was successful is
another. Currently, the measure of "success" is whether Scintilla compiles on
all platforms after a backported change. This process can be automated using hg
hooks and the "check.mak" makefile. By adding the following to .hg/hgrc:

  [hooks]
  pretxncommit.adddeps = test -z "`hg status | grep '^A' | grep '\.\(h\|cxx\)$'`" || make -f check.mak deps
  pretxncommit.compile = make -f check.mak

whenever a backported change is about to be committed, hg runs "check.mak",
which attempts to compile Scintilla on all platforms. If successful, the commit
is made. Otherwise, the commit fails and changes must be made before attempting
to commit again.

The file "check.mak" is designed to run on a Linux machine that has
cross-compilers for Win32 and Mac OSX. It does not necessarily produce any
binary builds of Scintilla that can be used -- it just ensures Scintilla can be
built without compile errors. How to obtain a set of cross-compilers is beyond
the scope of this document. At the time of writing, GCC 5.4 is used exclusively.

Not only does "check.mak" perform platform compile checks, but it also has rules
for manually running Scintilla's unit tests (which take too long to run
automatically as a pre-commit hook), creating a LongTerm3 release archive set,
and uploading documentation to the LongTerm3 website on SourceForge:

  make test
  make zip
  make upload

The last rule requires user credentials.

Backport Status
===============

This section mentions all upstream changesets that have either NOT been
backported, beginning at 6289:4c1084a571ff (Starting 3.x long term maintenance
branch), or have information worth noting.

6290:2378244bf3c7 Converted to Automatic Reference Counting.
6291:31466630bccc Using instancetype for constructors.
6292:7f58802368f4 Using modern Objective C literals and indexing.
6294:e1301b1d2321 Use property dot syntax.
6295:57988f82bf71 Indented consistently by using astyle.
  Cocoa platform only.
  None of these are backported since I am unsure if they are supported in C++11.
  Despite finding references to ARC and some Modern Objective-C dating back to
  2013ish, I also see that Clang 4.0 introduced support for some of this.
  However, Clang 4.0 was released in early 2017.

6304:b6cf154fe8d0 SciTE change log.
  Not backported, as this applies only to SciTE.

6309:2d4cb83e9297 Back down from gnu++17 to gnu++14 so can build with g++ on current Ubuntu.
  Not backported since only C++11 is supported.

6317:0f15d772bceb SciTE change log.
6319:a3b66b2525e7 SciTE change log.
  Not backported, as these apply only to SciTE.

6328:3c87cf6d2599 Update IDocument for version 4. Drop IDocumentWithLineEnd interface to just have IDocument but with all the methods from IDocumentWithLineEnd. This removes version checking (for now). Use dvRelease4 ID. Drop mask argument to StartStyling.
  Not backported since IDocument and ILexer interfaces should not change once
  published according to Neil. Since the only substantial change is changing the
  StartStyling() API, it does not seem worth creating a new IDocument4
  interface with an option mask argument. It would likely cause compiler issues
  too.

6329:6468941ee017 Updated documentation to match changes to IDocument and ILexer.
  Not backported since IDocument has not been changed.
  It may be worth committed a modification of the first diff though, if 3.8.0
  ends up using 64-bit types for Sci_Position and Sci_PositionU.

6330:59f341b22087 Deprecate single phase drawing.
6333:320418de6275 Clean whitespace.
  Not backported since the curses platform relies on single-phase drawing for
  now.

6345:faecbd0078e5 Merge Ilexer and ILexerWithSubStyles into ILexer4 to avoid need for version checking in 4.0. Use lvRelease4 ID.
  Partially backported with 6346:72bd27f81477 minus ILexer4, since the ILexer4
  interface being added cannot co-exist with the existing ILexer interface.
  (LexerModule.h uses a single typedef.)

6357:96232b746342 SciTE change log.
6361:69fddf8f8a15 SciTE changelog.
  Not backported, as these apply only to SciTE.

6372:cae69b34b92e Preparing for the 4.0.0 release.
6374:ec8e68de4ddb Delaying a day due to change with Lua in SciTE.
6375:4aaf170db91a Added tag rel-4-0-0 for changeset ec8e68de4ddb
  Not backported, since this is LongTerm3.

6394:dae03efac67d Update Xcode project files automatically for Xcode 9.
  Not backported, since Xcode 9 was released in late 2017.

6403:bd5c44cb0ab8 Updates for 4.0.1 release.
6404:e04bd73927ea Added tag rel-4-0-1 for changeset bd5c44cb0ab8
  Not backported, since this is LongTerm3.

6407:f60756d22ff3 Fix bad formatting.
  Not backported, as the bad formatting was not merged into the previous
  backport.

6409:c6a13f6eac24 Disable the animated find indicator on macOS 10.13 where it fails.
6410:29e81816b889 Change log.
  Not backported, since macOS 10.13 was released late 2017 and
  NSAppKitVersionNumber10_12_2 is probably not defined on earlier macOSs. I
  cannot find a good way to #ifdef around it.

6411:96becb885ce4 Updates for 4.0.2.
6412:ad210d76378f Added tag rel-4-0-2 for changeset 96becb885ce4
6417:f78045efae20 Add section for 4.0.3 and move posr-4.0.2 items into it.
  Not backported, since this is LongTerm3.

6425:73343682cbda Start of bidirectional code - implement SCI_SETBIDIRECTIONAL.
6426:0f7f5a382dbb Add ENABLE_BIDIRECTIONAL option to make files.
  Not backported, since it is unknown whether or not this feature will have any
  C++14 or C++17 features in it.

6432:b25c127aa6c5 Ensure build allows C++17. ARC setting is matching same setting at different scope so no effect.
6433:231ac99e1fdc Allow C++17 in all build and project files.
6435:5dd1b26df75f Replace Sci::clamp with C++ standard std::clamp function. std::clamp is from C++17.
  Not backported, since only C++11 is supported.

6438:f635874b303b SciTE changelog.
6439:0e036d7fa960 SciTE changelog.
  Not backported, as these apply only to SciTE.

6440:a1731ae83d2a Disable animated find indicator on macOS 10.12 as it causes drawing failures.
  Not backported, since macOS 10.13 was released late 2017 and
  NSAppKitVersionNumber10_12_2 is probably not defined on earlier macOSs. I
  cannot find a good way to #ifdef around it.

6446:f7abec3bbc7a SciTE change log.
6447:44ff2195a202 SciTE change log.
  Not backported, as these apply only to SciTE.

6450:7295a806b4c4 Updating for 4.0.3.
  Not backported, since this is LongTerm3.

6452:1bf8b7c50995 Update Cocoa test app to Xcode 9.2 settings.
  Not backported, since Xcode 9 was released in late 2017.

6453:71a51a9a6048 Added tag rel-4-0-3 for changeset 1bf8b7c50995
  Not backported, since this is LongTerm3.

6454:c25d3cb37f7d SciTE change log.
6455:b9e278677527 SciTE changelog.
6459:0aef625a6ab0 SciTE changelog.
  Not backported, as these apply only to SciTE.

6460:b4500f60b593 Added string_view to order.
  Not backported, since only C++11 is supported.

6464:fe5f45df61ce SciTE change log.
  Not backported, as this applies only to SciTE.

6465:cdfd8b285278 Update to c++17 so make_unique is available.
6476:59bafd0d2f77 Updated requied compiler versions.
  Not backported, since only C++11 is supported.

6632:8399b7723701 Change standard flag on MacOS as Xcode clang doesn't yet like c++17.
  Not backported, since only C++11 is supported.

6643:ebbb4e5aaf93 Update unit test Visual C++ builds to Visual C++ 2017 with /std:c++latest.
  Not backported, since only C++11 is supported.

6661:d03cd726962c New Xcode 9.3 so ran the updater which turned on some warnings and it fiddled with the projects and schemes.
6662:3c001296c0a4 Reverted #6488 as Xcode clang 9.1 now likes --std=c++17.
6664:0f1db0d9a0a6 Standardize on --std=c++17, avoiding GNU extensions and enabling clang 6.0.
6666:9561714c303b Updated due to allowing C++17 code now.
  Not backported, since only C++11 is supported.

6676:d48bdae67b33 Updates for 4.0.4.
6678:95fdb4c19b33 Added tag rel-4-0-4 for changeset d48bdae67b33
  Not backported, since this is LongTerm3.

6680:0161abb24da4 Bug [#2008]. Avoid warning unsigned >= 0.
  Not backported, since it is unknown whether or not this feature will have any
  C++14 or C++17 features in it.

6689:41dbff5a4813 Make method const as it is just a reader.
  Not backported, since return value depends on interface, which is different
  from single interface in 4.x.

6746:61e16d5c73cf Change log for SciTE for macOS.
6749:85d99f7c5c6d SciTE change log.
6757:56a46ce2e0b4 SciTE change log.
6779:d5508bacbfd4 SciTE change log.
  Not backported, as these apply only to SciTE.

6786:68c8592fe333 Specify type of std::clamp to avoid casting arguments.
  Not backported, since std::clamp is C++17 and Sci::clamp is not typed.

6922:d97cb73c8da7 SciTE change log.
  Not backported, as this applies only to SciTE.

6924:b9ab83221b03 Updates for 4.0.5.
6931:87dc832e3c94 Added tag rel-4-0-5 for changeset b9ab83221b03
6932:cc470382029e Add stub for next release.
  Not backported, since this is LongTerm3.

6936:c98e38d29c46 Include <string_view> in tests in case needed.
6937:5200f56c1494 Include <string_view> to allow future use in Platform interface and Unicode.
6941:8a34096cd01e Modernize Platform.h (4) - update Surface to use string_view for text arguments.
  Not backported, since only C++11 is supported.

6942:adbc779db70a Modernize Platform.h (5) - remove ElapsedTime.
  Not backported, since it was already removed in changeset 6876:a057d12cc6b9.

6943:39f2ec3334c1 Use string_view for UniConversion functions.
  Not backported, since only C++11 is supported.

6946:959308676456 Fix warning.
  Not backported, since it applies to a previous changeset not backported.

6947:fb52ef66ed47 Remove dependency on StringCopy and simplify constructor.
  Not backported, since only C++11 is supported.

6949:7747dc29d8a0 Fix warnings in debug assertions.
  Not backported, since it applies to a previous changeset not backported.

6950:682b634df52b Encapsulate WideCharToMultiByte and MultiByteToWideChar to simplify calling sites and standardize use of options.
  Not backported, since only C++11 is supported.

6951:b2a17a08a1f8 Replace ELEMENTS with std::size and drop inclusion of StringCopy.h.
  Backported only the latter bit since C++11 does not have std::size.

6961:d2563c53ab4c SciTE change log.
  Not backported, as this applies only to SciTE.

6962:514fde42ccbf Draw invalid bytes in DBCS when detected as blobs in a similar way to UTF-8.
  Backported, but replaced std::string_view usage with const char* and size_t
  components.

6964:d7ec2cdbcd16 If decoding DBCS text fails, use the MacRoman encoding to ensure something is visible.
  Not backported, as it makes use of a previous changeset not backported and is
  not easy for me to support if I patched it.

6970:b78f7643ae73 Add definitions for bidirectional support to Platform.h and provide empty implementations for each platform.
6971:e51e7a972b89 Implement bidirectional mode bidiL2R for DirectDraw on Win32.
6972:f30d0a228046 Update for bidirectional support.
6973:7570322b0219 Added credits.
7006:a6d3cefd4f79 Add TabPositionAfter method to IScreenLine as this calculation is needed on each platform and it allows extension to custom tab stops.
  Not backported, since previous bidirectional support was not backported.

7009:e1100c6feaaf Add function to find a UTF-16 position in a UTF-8 string.
  Not backported, since it is only used in bidirectional support at the moment.

7011:23a98ab36601 Define IScreenLineLayout as the main interface for implementing bidirectional features by platform code.
7012:5f4011e010f9 Implement IScreenLineLayout for Cocoa Core Text as ScreenLineLayout.
7013:0d86879c5ca5 Make virtual space selections visible in bidirectional mode.
7014:39d3e00c381a UpdateBidiData is called by EditView but doesn't use any EditView fields so make it static.
7015:6a7459cd08f9 Updated to mention bidirectional works on Cocoa.
  Not backported, since previous bidirectional support was not backported.

7026:4377a8d710e1 Update Cocoa enumerations to current names instead of deprecated names.
  Not backported, since many of these enumerations are not available for older SDKs.

7027:b71248119e8b Remove compile-time ENABLE_BIDIRECTIONAL option as bidirectional feature is now controlled completely at run-time.
  Not backported, since previous bidirectional support was not backported.

7033:5da90aad11da Updates for 4.1.0.
  Not backported, since this is LongTerm3.

7034:0dc20d87a4f9 Note that Cocoa also supports bidirectional text.
  Not backported, since previous bidirectional support was not backported.

7055:bb3c92f403f7 Added tag rel-4-1-0 for changeset 0dc20d87a4f9
7059:455f134efbc1 SciTE change log.
7061:d744568dfaa5 SciTE change log.
  Not backported, since this is LongTerm3.

7063:0d5edc93e280 Optional indexing of line starts in UTF-8 documents by UTF-32 code points and
  Backported, but replaced std::string_view usage with const char* and size_t
  components. Also used const_cast where appropriate to fix compile errors.

7066:ee645426b872 Add SciTE credit.
7067:43101fb47a25 SciTE change log.
  Not backported, since this is LongTerm3.

7069:e65cfc5348a5 Change lifetime of textLayout for bidirectional so it is always released in
7071:d9e28bcc6cf9 Bug [#2030]. Fix Win32 crash setting technology to default after bidirectional
  Not backported, since previous bidirectional support was not backported.

7074:b190647b5084 SciTE change log.
7079:744cd6e004ae Updates for 4.1.1.
7080:59fdd1f4d5cd Updated change list for 4.1.1.
7082:058cd4b189e6 Added tag rel-4-1-1 for changeset 892c361b3969
7083:d87b627094ad Fix version number.
7084:cd27559c2a65 Moved tag because of doc fix.
7085:fcf47c352832 Updated outdated text.
7086:c8643589ba1d Added tag rel-4-1-1 for changeset fcf47c352832
7091:575636ffe226 Added section for next release.
7095:58524eea6d35 SciTE change log.
7101:f4988dfccc31 Updates for 4.1.2 release.
7103:20455b6997e3 Added tag rel-4-1-2 for changeset 927e7d62e917
  Not backported, since this is LongTerm3.

7104:9b7f24b1b150 Fix crash when particular patterns of invalid UTF-8 led to failure to create a
  Not backported, since previous bidirectional support was not backported.

7109:29f0ca6d2d1b Improve performance of Editor::RangeText by avoding per-character checks.
  Backported, but with const_cast to file compile error.

7121:2f5d50043861 Bug [#2055]. Use dark info bar background when system is set to Dark Appearance.
  Not backported, since its parent changeset 7026:4377a8d710e1 was not
  backported.

7172:05e2d46ae4c0 SciTE change log.
7177:08ccc2c490c2 SciTE change log.
  Not backported, since this is LongTerm3.

7187:29c12794f87e Stop specifying -std:c++latest as that is no longer needed to enable C++17
  Not backported, since only C++11 is supported.

7194:b428bfb5a730 Bug [#2022]. Fix incorrect horizontal offset on macOS 10.14 Mojave.
  Not backported, since I have no easy way to test if this compiles. I'd also
  like to assume LongTerm3 clients are only interested in earlier versions of
  macOS.

7197:1484a537b380 Updates for version 4.1.3.
7198:974d0f564d0d Added tag rel-4-1-3 for changeset 1484a537b380
  Not backported, since this is LongTerm3.

7250:f77887e669fc SciTE history.
  Not backported, since this is LongTerm3.