Split repository into `master` (library source) and `support` (CI, docs, examples) branches. #287

This PR removes documentation, CI scripts, and examples from the master branch, moving it to a support branch instead.

This reduces the number of files that need to be imported into the bitcoin core subtree, and should make subtree bumps in bitcoin easier to review since they will no longer contain extraneous changes. It should also facilitate review within the libmultiprocess repository so PRs that actually modify the library can receive greater attention and PRs that only change support files can be merged more quickly.

This PR is an alternative to trying to exclude support files from the bitcoin core subtree (https://github.com/bitcoin-core/libmultiprocess/pull/276) which is a more complicated change that does not have same review benefits. The idea was originally brought up in #232 (comment).

This PR depends on #288 should be merged after it.

<!--e57a25ab6845829454e8d69fc972939a-->

The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.

<!--021abf342d371248e50ceaed478a90ca-->

Reviews

See the guideline for information on the review process.

If your review is incorrectly listed, please copy-paste <code>&lt;!--meta-tag:bot-skip--&gt;</code> into the comment that the bot should ignore.

<!--174a7506f384e20aa4161008e828411d-->

Conflicts

Reviewers, this pull request conflicts with the following ones:

• #296 (ci: Bump channel to nixos-26.05 by maflcko)
• #288 (Create support branch for CI scripts, documentation, and examples by ryanofsky)
• #274 (Add nonunix platform support by ryanofsky)
• #269 (proxy: add local connection limit to ListenConnections by enirox001)
• #212 (ci: add newdeps job testing newer versions of cmake and capnproto by ryanofsky)
• #209 (cmake: Increase cmake policy version by ryanofsky)
• #204 (cmake: support default build and test workflow by purpleKarrot)
• #175 (Set cmake_minimum_required(VERSION 3.22) by maflcko)

If you consider this pull request important, please also help to review the conflicting pull requests. Ideally, start with the one that should be merged first.

<!--5faf32d7da4f0f540f40219e4f7537a3-->

<!-- begin push-2 -->

Updated f26575b0f42210ee2f5515a9980b6710f73223aa -> 5432abc2ca9375225bf0ec70e06b5fd642b592d3 (pr/supportm.1 -> pr/supportm.2, compare)<!-- end --> including #286 to fix sanitize CI error https://github.com/bitcoin-core/libmultiprocess/actions/runs/26921735329/job/79423434803

I agree with @Sjors's opinion:

I think having a separate support branch would be especially confusing to anyone new to this repository. If it's not the default branch, then the repo looks undocumented and untested. If it is the default branch, now it's difficult to contribute because you need to deal with two branches.

Why don't you just use filtered subtrees? I think that's a better solution and cleaner instead of making different branches that contain whole different codebases.

This is what the repo will look like after this change: https://github.com/ryanofsky/libmultiprocess/tree/pr/supportm

The README points to the relevant documentation on the support branch. That's easy enough to find when browsing on Github. But when someone checks out the repo on their own machine, the documentation is harder to find, because you have to switch branches or use a second worktree with the support branch checked out.

Updating documentation along with code changes becomes more tedious, because you have to open two separate pull requests. New contributors may initially be confused about what branch to open a PR to. Both aren't huge issues though.

Perhaps a middle ground could be to:

• move CI to a separate (ci) branch
• put examples in a new repo
• keep documentation in this repo

Thanks it's true this PR is taking a maximalist approach. I mostly just want to get rid of CI code in the master branch and would be ok with leaving examples and markdown documentation where they are. But I do think they would be better to move because:

• Current documentation isn't very good, and it's hard for me to imagine it getting better without being able to quickly merge changes to it and treat it more like a wiki. I actually think moving the documentation to a wiki could be a good idea, but tooling around wikis seems pretty limiting without ways to comment on changes, write good log messages, or edit files locally.

• In all cases where markdown changes and code changes are currently being made in the same PR I think it's bad. This PR is not moving API documentation or user-facing release notes where it would make sense to commit documentation and code changes together. It is only moving design documents and an internal changelog which are better to update separately. Bumping a version number should not require updating documentation at the same time, for example.

But when someone checks out the repo on their own machine, the documentation is harder to find

I think this could be improved by mentioning the git worktree add .support support command in the readme. The readme is very short and does link directly to the documentation and say where it lives, so I feel like it explains they layout pretty clearly, though perhaps it could be clearer.

Why don't you just use filtered subtrees?

This doesn't deal with the problems I want to solve of being able to update CI scripts and documentation and other ancillary files more freely and give more attention to the PRs affecting master and bitcoin core. Filtering subtrees in the bitcoin core repository only affects the review that happens that repository, which is normally less detailed and not as useful as the review that happens here.

But if you have specific concerns with this approach, would be good to know about though. I've been using branches with different trees for a very long time locally and haven't run into problems with them. And it seems github support is very good as well.

Perhaps a middle ground could be to:

* move CI to a separate (`ci`) branch

* put examples in a new repo

* keep documentation in this repo

that's better yeah but it's too much. there are a lot things are separated

This doesn't deal with the problems I want to solve of being able to update CI scripts and documentation and other ancillary files more freely and give more attention to the PRs affecting master and bitcoin core. Filtering subtrees in the bitcoin core repository only affects the review that happens that repository, which is normally less detailed and not as useful as the review that happens here.

I am thinking about a solution is similar to this and I think it should be more efficent. why don't make a distribtuion branch and keep the master as it is? Also, we can make a CI workflow to automate the distribution by making the github bot pushing the source files only that's required to bitcoin core and exclude docs, ci and examples. I think that's the optimal solution for the problem. you kept the source without possible issues in future and without make it weird for new people

I think this could be improved by mentioning the git worktree add .support support command in the readme.

Yes, that should be fine. Although perhaps it's nicer / more intuitive to have a separate doc branch, and avoid a hidden directory:

To fetch documentation, use git worktree add doc doc

(doc can be added to .gitignore)

Then you might as well do the same with the examples.

re: #287 (comment)

Yes, that should be fine. Although perhaps it's nicer / more intuitive to have a separate doc branch, and avoid a hidden directory

That's a good point and there is actually no reason to have a hidden directory, so the instructions are now simplified to just recommend git worktree add support. It's still using one branch instead of multiple though.

re: #287 (comment)

I am thinking about a solution is similar to this and I think it should be more efficent. why don't make a distribtuion branch and keep the master as it is?

So your idea is to have a master branch that is unchanged and contains all files, and a distribution branch which contains a subset of master (only source files and tests). I can see how this could possibly avoid some drawbacks of the subtree split approach (https://github.com/bitcoin-core/libmultiprocess/pull/276) since it would not require changes to the Bitcoin core subtree import steps or linter, and like all 3 approaches it would remove unused files from the Bitcoin core repository. But it would require a bot or extra steps to keep the two branches in sync, and changes on the different branches would have different hashes and signatures. It also does not solve the problem I want solve of requiring a higher review standard for changes which affect Bitcoin core, while making it easier to merge changes which do not affect Bitcoin core. Also, I still do not know what specific drawbacks you see of moving extraneous files to a support branch. It seems to me this provides a clear separation between files that exist for different purposes, and would not create practical difficulties.

<!-- begin push-3 -->

Rebased 5432abc2ca9375225bf0ec70e06b5fd642b592d3 -> 2c078dac72bc9fd4b43ef4485601f1f63f04b8f3 (pr/supportm.2 -> pr/supportm.3, compare)<!-- end --> due to conflicts, also adding worktree command to readme.

Occurred to me that bitcoin/bitcoin#33362 is a good example of why I think separating CI scripts from code would be good.

If the CI change in that PR was done in its own PR, instead of combined with python test and test framework changes, the downsides of adding a static IP would have been more likely to be considered since adding it would be the main change not just a secondary tweak. A separate PR could also have attracted more review from reviewers who care about CI configuration and usability but may not be interested in reviewing a larger code change.

Occurred to me that bitcoin/bitcoin#33362 is a good example of why I think separating CI scripts from code would be good.

If the CI change in that PR was done in its own PR, instead of combined with python test and test framework changes, the downsides of adding a static IP would have been more likely to be considered since adding it would be the main change not just a secondary tweak. A separate PR could also have attracted more review from reviewers who care about CI configuration and usability but may not be interested in reviewing a larger code change.

I understand this is subjective, but I don't think this is true. I didn't see that this would break from reviewing the code, and I don't think anyone would have caught this, unless they try to run two CI containers at the same time.

I am not sure if it is beneficial to force that stuff is split up. In 33362 those were already two commit, and it would have been trivial to ask the author to split those into two pull requests, if there was a benefit.

Conversely, it could be confusing if CI changes are forced to be always separate from code changes. E.g. https://github.com/bitcoin/bitcoin/pull/34662/changes just go hand in hand. That simple pull request would then be three separate changes/pulls:

• Fix contrib
• Bump
• Remove the unused workaround

Concept ACK