Open Source Project Structure
Do as the Romans do
Most open source projects follow common pattern for directory structure which looks somewhat like this:
build dist samples src tests readme.md
This makes sense and easy to understand - you put your source files under
src, distribution files go to
dist, unit tests under
tests. If you have a build utility it goes under
build, samples take their own place and so on. Nothing wrong with that, so I mostly follow it for Blogifier and ended up with this structure:
docs plugins common src app core tests core.tests readme.md
docs has documentation in markdown format. I decided against using Github's wiki, because documentation is version specific and keeping it in the wiki would require maintain all the version differences. This way, you pull docs along with source code and, at least in theory, they match.
plugins would have any extensions to the core functionality, like custom themes and widgets. The
common project has all the common plugins, to build new developer would add another project here. Resulted DLL could be side-loaded at run time, so down the road it could be pulled from common store or repository.
src has two projects. One is
app which is web application or blog itself. It is ASP.NET Core application utilizing MVC for the blog features and Razor Pages for admin panel. Distinction is because MVC ideal for manipulating blog routes and plug in on the fly themes and widgets. Razor Pages are great in separating application by features so it can be structured really nicely. Second project here is
core - class library with core back-end functionality (services, data access etc.).
tests currently has unit tests mostly covering logic in services. If there need for example to have integration testing, the
app.tests project can be added here. Same goes for plugins - you write your plugin - you can add tests for it here, in
Visual Studio has a feature called
solution folders - whenever you add new project to solution it is added as virtual folder, no physical folder actually added to the file system. At least not where you would expect it. This can be very misleading and, when you switch to file-based editor, like VS Code or Atom, your projects look messed up. To avoid this, I always create physical folder and select it for new project so that virtual and physical match.
Not a fan of deep nesting, that's why
plugins at top level instead of nesting under
src. Just a personal preference.
I started by creating wiki pages in Github, but quickly realized this is going to be hard to keep up with changes in every version. So instead of having
this only applies for version 1.2.3 statements, all documentation is going into
docs folder and naturally version specific. Just as
readme.md it is all in markdown format.
Hope this makes sense and easy to follow, if you have better ideas comments are welcome.