Typical Stash Structure?


We are debating restructuring our VCS, coming from SVN with no code-review, to Stash/git with code review by module. I think I know how to structure it, but have a few general questions. I had planned on breaking our project down into ~10 sub-modules, and then assigning maintainers to each of them, who are responsible for code reviews.

The major issues I seem to forsee involve tying them all together. What is the best way to do this...? I could use Maven, but I was thinking of just using git-submodule to bring them together in one big repository.

The other major issue seems to be how to handle cross-module changes. If your change requires changes in both module A, and module B, in order to build, how would you do this? With a code-review process, it seems like there would always be a state where your main build breaks, because you would need to complete two seperate code reviews.

Are we approaching this the right way? Is there a better way to structure this?

1 answer

1 accepted

1 vote
Accepted answer

Hi Jon,

I was hoping someone would give you an intelligent answer, but I guess you'll have to make do with my ramblings instead.

You've asked one of the hard questions around DVCS, and as such sadly there is no silver bullet. :(

Submodules are definitely the first thing that comes to mind. Although you may have read a few people warning against them. My biggest gripe is the default of having the module URLs checked into the repository, which means if you ever decide to move server locations your previous builds are all going to break. To me it shows a lack of understand of the problem they're trying to solve. The direct alternatives to submodules include subtree and repo.

At Atlassian we use basically use (and have since SVN) Maven, which I think is a more powerful and robust implementation of dependency management, something submodules only scratch the surface of. Obviously the downside is that setting up the requisite builds can be cumbersome, and making an 'atomic' change to multiple modules very tricky. One can argue that this forces developers to think more carefully about their API boundaries, but sometimes it can be a right pain.

If many of your modules don't change all that often, or change independently, then Maven is probably a safe bet. If you are frequently making changes across modules then it may be more convenient to use submodules or something more Git-specific. Alternatively, there is always the fallback option of having a single, uber repository. This obviously circumnavigates the problem of cross-repo reviews. The biggest downside can be ballooning repository size and build times, which if unchecked can be harder to rectify later on.

Build wise, if you decide to go with Maven, then you would most commonly have separate builds for each module, and you hopefully wouldn't merge and/or release until each build passes. Alternatively you could have a single plan which builds all the modules in sequence. The same is roughly true for submodules, although I suspect you're more likely to have a single build anyway.

I hope this helps somewhat? Let me know how it all goes.


Hi Charles,

We use Maven already, but my plan with using seperate repositories was to asign ownership of modules, and then restrict merging to the master to the owner...

More and more, I'm thinking maybe the best way is to have a single repository, but have a self-enforced rule of who to assign a pull-request review to, but not actually enforce it at the repository level...changing multiple seperate repositories at the same time could become a huge issue, if they are dependent on eachother. Instead, you could just make one pull request, and assign it to all of the appliciable owners?


Hi Jon,

Having a single repositories is, without a doubt, the easiest configuration to manage, especially when the dependencies are entwined. As I mentioned above, the danger is that it's gets harder to untangle later, and your builds and repository size can suffer over time. The good news is that if you ever need to extract a sub-repository for whatever reason Git makes that very easy.

You may want to have a quick look at git subtree which may, or may not, be useful for maintaining separate repositories that also live your single, parent one.

Best of luck.


Suggest an answer

Log in or Sign up to answer
Community showcase
Published Nov 06, 2018 in Bitbucket

Upgrade Best Practices

Hello! My name is Mark Askew and I am a Premier Support Engineer for products Bitbucket Server/Data Center, Fisheye & Crucible. Today, I want to bring the discussion that Jennifer, Matt, and ...

1,961 views 7 10
Read article

Atlassian User Groups

Connect with like-minded Atlassian users at free events near you!

Find a group

Connect with like-minded Atlassian users at free events near you!

Find my local user group

Unfortunately there are no AUG chapters near you at the moment.

Start an AUG

You're one step closer to meeting fellow Atlassian users at your local meet up. Learn more about AUGs

Groups near you