3

My friend is building a small open-source project with a few convenience functions. He'd like to release both JS, PHP and Python versions of the package to npm, packagist and pypi. The main part of the package is just data that can be shared, so the actual code to translate is very small.

Should I recommend him to build three different Github repositories (js-theproject, php-theproject and py-theproject), or a single repository that contains all three folders and a separate "data" directory?

As I see it, the advantage of using a single repository would be to keep track issues in a single place, and no worries about updating the data file in multiple places or making releases in multiple places. The advantage of using three repositories would be to make it more clear what language the packages are intended for, and make it easier for those who search for "js [solve what the package solves]" to find the repository, both in github and google, so some kind of SEO.

I tried to find other projects that have solved this problem, but it seems most small projects are released for just a single language.

3
  • I am failing to see any good reason to have three separate repositories, and the very obvious downside of trying to keep the data in sync between the three repositories. Could you please edit your question to explain what you think the advantages of this approach would be? Commented Jul 13, 2022 at 12:08
  • I am not so experienced so to me it is not obvious. I added sentences about what I see as the advantages, does it look right?
    – Anna
    Commented Jul 13, 2022 at 12:13
  • 1
    One idea too small to be an answer: have you considered to provide the data online and let the different implementations download it when it changed? That way, you don't have to update the software packages when only data has changed. Commented Jul 13, 2022 at 18:41

1 Answer 1

8

It doesn't really matter which approach you choose. Both using a monorepo and separate repos are reasonably common approaches.

Keeping all variants in a single repository is definitely simpler to manage, and updating the data is straightforward. It is also straightforward to make cross-cutting changes, such as changing the data format and all dependent software in one go.

But there are some downsides with tooling, e.g. if language-specific tools expect some configuration to exist in the top-level directory of the repository. If you have an automated test suite or a CI server, you may be re-running tests for all languages even only code for one language changed. This might also complicate contributions for a single language's version. It may be unclear how version numbers for the packages relate to versions in your source control system. As a problem specific to GitHub, the releases page will also be a mess.

Having separate repositories for each language is definitely more complex, but also more flexible. Each package can be developed independently, and it's easy to version the packages separately.

Downsides are greater effort for updating the data. You can keep the data in a separate repository and integrate it as a git-submodule. However, a git-submodule references a specific commit – you'd have to update all dependent repositories to point to the updated version. This turns a single data update into an O(n) effort, though using a bot to automatically generate the necessary pull requests can reduce the human effort here. Alternatives like git-subtree that copy the data into each repository aren't any easier either.

Another downside is the difficulty of making cross-cutting concerns across all versions. It is possible that less popular packages lag behind and do not get new features.

While both approaches are good, they have distinct and largely opposite benefits/downsides. You can therefore decide by thinking about typical usage patterns:

  • If data updates are frequent but code changes are rare, consider a single repository.
  • If data updates are rare but code changes are frequent and independent, consider a separate repository per package.

This is not an either/or-solution. It is also possible to start with a single repository, and to spin out individual packages as they mature into an independent project.

1
  • Thank you very much amon! Your clear summary of the trade-offs helped me a lot.
    – Anna
    Commented Jul 13, 2022 at 19:04

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.