From 1fbf09c30930a0cb2e8cc613555ee2559c2af010 Mon Sep 17 00:00:00 2001 From: PulkoMandy Date: Sun, 23 Feb 2025 10:34:02 +0100 Subject: [PATCH] Internals documentation: add notes about the process without vendor branches This is still used in various places, so we should be clear about how it is supposed to be done. It should avoid people learning from repeating errors that others have already made. Change-Id: I2468e51e62658bfad499c22294dd8a34c8aa8c90 --- docs/develop/build/sourcecode.rst | 42 +++++++++++++++++++++++++++++-- 1 file changed, 40 insertions(+), 2 deletions(-) diff --git a/docs/develop/build/sourcecode.rst b/docs/develop/build/sourcecode.rst index f7980a223e..7630c51993 100644 --- a/docs/develop/build/sourcecode.rst +++ b/docs/develop/build/sourcecode.rst @@ -87,8 +87,11 @@ the MIME database. * 3rd_party - Developers custom files. Used for various side projects from Haiku developers, useful personal scripts, and integration with other tools and projects such as virtualization software -Managing GCC and binutils updates using vendor branches -------------------------------------------------------- +Managing 3rd-party code +----------------------- + +GCC and binutils updates using vendor branches +:::::::::::::::::::::::::::::::::::::::::::::: The buidtools repository uses vendor branches. This concept originates from `the SVN Book `_ but applies just as well to Git. This organization allows to clearly separate the imported code @@ -173,3 +176,38 @@ Comparing the two versions is easy because you can refer to them by branch names .. code-block:: bash git diff vendor-binutils master -- binutils + +Third party code in Haiku without vendor branches +::::::::::::::::::::::::::::::::::::::::::::::::: + +The Haiku main repository contains third party code that does not use vendor branches. This +can be for various reasons, such as: + +- Imported files are only a very small subset of another project +- The upstream project is not developped actively anymore +- The import is not done from a specific release of the upstream project, but done piecewise. + +Some examples of this are: + +- All the code in src/libs (often not maintained upstream or very simple), +- The NetBSD DNS resolution code (one version was packaged as a separate "netresolv" package, but + that approach was abandoned by NetBSD) +- Parts of glibc, musl and BSD C library that are reused in libroot (each file imported + independently as needed) +- FreeBSD and OpenBSD network drivers (each driver synchronized as needed) + +In this case, since there is no branch to track where the upstream code came from and what changes +were made, a few specific steps should be taken to avoid confusion and possibly losing some of our +changes and fixes: + +- Mark all changes made on Haiku side with a __HAIKU__ preprocessor guard. This makes them easy to + identify, and allows upstream to integrate these changes if they want to +- When importing newer versions, note in the commit message where you got the files and which + version you used (either a release number, or the commit identifier if using files directly from + upstream source control) +- Keep the changes to a minimum to ease future sycnhronizations with upstream. In particular, it + is often not possible to build these files with -Werror due to type declaration differences + +When importing new version of the files from upstream, make sure to review all the places where +there are __HAIKU__ guards, and consider wether they still apply in the new version, or if the +upstream code has been changed so they can be removed.