Hi Yuan, Thank you for the detailed suggestions and for supporting this direction.
I agree that we should first prepare a short packaging and installation design before implementing the CPack configuration. It will clarify the library compatibility and SONAME policies, installation paths, and how downstream projects should use libtsfile through CMake and pkg-config. It will also cover the support scope for static and shared libraries, CLI naming, and the logical separation of runtime, development, and CLI components. These components can remain logically consistent across platforms, while the actual package layout follows each platform’s conventions. For example, Debian and Ubuntu may use separate runtime, development, and tools packages, while Homebrew may use a single formula containing the library, headers, and tools. Regarding platform priority, I also agree with starting with Homebrew and Debian/Ubuntu. Once the installation conventions and CI workflow are stable, we can consider RPM, Fedora, and EPEL based on actual user demand and the available maintenance capacity. For dependency management, native packages should prefer system dependencies. If portable packages need to bundle dependencies, we will follow the outcome of the third-party dependency discussion and review the corresponding LICENSE and NOTICE content. The packages will be built from community-approved source releases, remain traceable to the corresponding versions, and be clearly distinguished from official Apache source releases. In addition to package generation, the CI workflow will cover clean installation, building and running an independent CMake consumer project, upgrades, uninstallation, and checks for unexpected files remaining after uninstallation. Regarding the ownership and long-term maintenance of public testing repositories, I prefer not to assume a specific model at this stage. We can first complete the packaging and CI workflow. Once the work is mature and we are ready to establish public channels, we can discuss and determine repository ownership, publishing permissions, and maintenance responsibilities within the community. The handling of RC packages can also be discussed separately at that stage, with clear measures to avoid confusing them with approved releases. As the next step, I will prepare the packaging and installation design for community review and then proceed incrementally through separate pull requests. Thank you again for the helpful feedback. Best, Colin At 2026-07-22 18:16:25, "Yuan Tian" <[email protected]> wrote: >Hi Colin, > >Thanks for proposing this. I support the overall direction (+1). Providing >standardized installation artifacts and support for mainstream package >managers would significantly lower the barrier to using libtsfile. > >I have a few suggestions: > > 1. Clarify the boundary between Apache releases and downstream packages > >Apache community-approved source releases should remain the basis for these >packages. If the project maintains and publicly distributes convenience >binaries, they should: > > - Be built from a source release that has passed the community release > vote. > - Use the same version as the corresponding source release and remain > traceable to it. > - Comply with ASF requirements concerning LICENSE, NOTICE, third-party > dependencies, branding, and trademarks. > - Avoid presenting unapproved nightly, snapshot, or RC packages as > general-purpose installation channels. > >Homebrew Core, Debian, Fedora, and similar repositories are downstream >distribution channels. Packages published through them should not be >described as new official Apache releases. The project documentation should >continue to point users to the ASF’s official source distribution. > > 2. Keep the logical components consistent while following platform > conventions > >I agree with logically separating the artifacts into runtime, development, >and CLI components. On Linux, the packages could follow a structure such as: > > - libtsfile or libtsfile<SONAME>: runtime shared library > - libtsfile-dev or libtsfile-devel: public headers, CMake package > configuration, and pkg-config metadata > - tsfile-tools: command-line tools > >However, we do not necessarily need identical physical package layouts >across all package managers. For example, Homebrew may be better served by >a single formula containing the library, headers, and tools, while Debian >and RPM packages can use finer-grained component separation. > > 3. Define the ABI and SONAME policy before publishing the first binary > packages > >Once packages enter public repositories, changing library names, >installation paths, or the SONAME becomes more costly. Therefore, I suggest >defining the following first: > > - Public ABI compatibility rules > - Conditions for updating SOVERSION and the SONAME > - CMake imported target and pkg-config package names > - Default installation paths and CLI names > - Support scope for static and shared libraries > >We could first document these decisions in a short packaging and >installation design before implementing the CPack configuration. > > 4. Handle dependencies differently for native and portable packages > >I agree that native Debian, Fedora, and Homebrew packages should prefer >system dependencies. This is more consistent with the maintenance practices >of those distributions and reduces duplicated packaging and security-update >work. > >If portable binary packages need to bundle dependencies, the approach >should follow the outcome of the ongoing third-party dependency discussion. >The bundled dependencies and corresponding LICENSE and NOTICE content >should also be fully reviewed. > > 5. Introduce platform support incrementally > >To avoid maintaining too many platforms at the beginning, I suggest >starting with: > > - Homebrew, to validate the macOS installation workflow > - Debian/Ubuntu, to validate the runtime, development, and CLI package > separation > >Once the installation conventions and CI are stable, support could be >extended to RPM, Fedora, and EPEL. The final priority should also consider >actual user demand and whether the community has enough maintainers to >support each channel over the long term. > >In addition to package generation, the CI should verify clean installation, >building and running an independent CMake consumer project, upgrades, >uninstallation, and whether any unexpected files remain after uninstalling. > >Before setting up public testing repositories, I also suggest clarifying: > > - Who will maintain each distribution channel over the long term > - Whether the testing repositories will contain only experimental > packaging of approved releases or also release candidates. If RCs are > included, access and promotion should remain limited to the development > community so that they are not mistaken for official releases. > >Overall, I support starting with the installation layout, CMake and >pkg-config metadata, ABI and SONAME rules, and local package generation, >and then proceeding incrementally through separate pull requests. > >Thanks, >Yuan Tian > >On Wed, Jul 22, 2026 at 2:37 PM ColinLee <[email protected]> wrote: > >> Hi all, >> >> >> Currently, TsFile C++ users generally need to build from source and >> prepare the required dependencies themselves. To simplify installation, I >> propose gradually supporting Homebrew, APT, Yum/DNF, and other mainstream >> package managers for installing libtsfile, development headers, and >> command-line tools. >> >> >> Apache source releases approved by the community will remain the basis for >> building these packages. I suggest proceeding in the following stages: >> >> >> 1. Standardize installation artifacts >> >> >> Provide consistent installation rules for libtsfile, public headers, CMake >> Package Config files, pkg-config metadata, and CLI tools. We should also >> define the library version and SONAME policy. >> >> >> 2. Support local package generation >> >> >> Use CPack to generate .tar.gz, .deb, and .rpm packages. The initial >> packages can be divided into runtime, development, and CLI components for >> CI validation and early user testing. >> >> >> 3. Improve third-party dependency management >> >> >> This work will be based on the ongoing third-party dependency discussion: >> >> >> https://lists.apache.org/thread/1ssk1rot302cx88pkt3rvzxjr19kpppr >> >> >> Native Debian, Fedora, and Homebrew packages should use system >> dependencies, while portable binary packages may use pinned bundled >> dependencies. The final implementation will follow the outcome of the >> community discussion and vote. >> >> >> 4. Build package CI >> >> >> CI should validate package generation, installation, upgrade, and >> uninstallation. It should also use an independent CMake example project to >> verify the installed libtsfile library and headers. >> >> >> 5. Publish packages incrementally >> >> >> We can first provide community testing channels such as a Homebrew tap and >> test repositories for APT and Yum/DNF. Once the process is stable, we can >> gradually apply for inclusion in Homebrew Core, Debian/Ubuntu, Fedora, and >> EPEL. >> >> >> Official repositories will require platform-specific packaging files, such >> as a Homebrew Formula, Debian packaging files, and an RPM spec, rather than >> directly using the CPack-generated packages. >> >> >> I would especially appreciate community feedback on: >> >> >> - Whether the proposed package and component structure is appropriate. >> - Which operating systems and package channels should be prioritized. >> >> >> If the community agrees with this direction, I will start with the >> standard installation rules and local package generation, and submit the >> implementation incrementally through separate pull requests. >> >> >> Comments and suggestions are welcome. >> >> >> Thanks, >> Colin
