Support for Drupal 7 is ending on 5 January 2025—it’s time to migrate to Drupal 10! Learn about the many benefits of Drupal 10 and find migration tools in our resource center.
Problem
- The 99% use-case of Drupal is a single site without multi-site functionality — but yet, we throw that entire concept into everyone's face.
Goal
- Simplify Drupal's directory layout for single-site installations.
Proposed solution
-
Ditch
/sites/all/*
completely in favor of top-level/*
directories.(Replace
*
with "modules", "themes", "profiles", etc.)
Related issues
- #22336: Move all core Drupal files under a /core folder to improve usability and upgrades
- #562042: Search for install profiles in sites/[all|site]/profiles folders, and move core profiles into /core/profiles
- #1055862: Require sites.php to opt-in for multi-site support/functionality
- #1055856: Optimize settings.php discovery
Change notices to update
Comment | File | Size | Author |
---|---|---|---|
#39 | drupal8.sites-all-top-level.39.patch | 14.23 KB | sun |
#39 | interdiff.txt | 687 bytes | sun |
#15 | drupal8.sites-all-top-level.15.patch | 14.13 KB | sun |
#15 | interdiff.txt | 5.23 KB | sun |
#6 | drupal-1724252-6.patch | 14.16 KB | tim.plunkett |
Comments
Comment #1
sunThis patch reveals that I sneaked 99% of this change into core already. :-D
Love this patch.
Comment #2
sunComment #3
webchickThis makes me smile so hard. :)
Comment #4
quicksketchYay yay yay! Wow I can't believe all the pinnings are there already. Nice work on #562042: Search for install profiles in sites/[all|site]/profiles folders, and move core profiles into /core/profiles :D
I hope more justification isn't needed than sun has given already, but overall this is going to be HUGE win for new users to Drupal. Even today people are constantly putting modules and themes directly into the root /modules and /themes directories. Now that we've moved the root directories, people have no idea where modules and themes live at all (at least not without starting to dig through directories). Moving the end-user modules/themes to the root level let's people do what they've intuitively been wanting to do for years.
Comment #5
Bojhan CreditAttribution: Bojhan commentedAwesome, thanks!
Comment #6
tim.plunkettTried to clean up references to sites/all.
So cool!
Comment #7
sunOh, awesome! Thanks @tim.plunkett! -- that's way more docs to update than I imagined :)
I think we need to prefix the directory with a slash in order to make any sense of the resulting sentences :)
The sites/all/README.txt is definitely obsolete with this patch.
However, I wonder whether we want to move it into sites/README.txt instead?
Essentially, that new README.txt would be the ideal place to describe how the multi-site functionality works, how to enable it (if it needs to be enabled at some point in the future), and potentially even to move the 2 gazillion lines of comments about the settings.php discovery out of default.settings.php into it...? :)
Comment #8
webchickPossibly, but the last time we touched that file it was 3+ months and 80+ comments so I'd recommend deferring that to a follow-up.
Comment #9
sunDeferring that optimization to a follow-up makes sense, too. :)
That said, can we delete
/core/modules/README.txt
& Co with this patch?Those clarifications (tl;dr: "This is core; don't fuck with me.") look unnecessary to me if there are top-level modules/themes/profiles directories already. (?)
Comment #10
webchickNo, unfortunately not because Git will not let you check in empty directories. :\ That's why they're there.
Comment #11
webchickOh, I'm sorry. /core/modules/README.txt. Yes, that's probably fine.
Comment #12
willvincent CreditAttribution: willvincent commentedActually, any file in a directory will allow you to check in/out "empty" directories with Git. Even if those are blank files. If the whole purpose of a readme file is to be able to check in an otherwise empty directory, it might make sense to place an empty dot prefixed file there instead. Good options might be .empty, .blank, or .placeholder... or of course an empty .gitignore would also do the trick. :)
Comment #13
webchickRight, that's true, but it doesn't hurt to put docs in here too to explain how the directories are working, so we went with that. sun's actually talking about different README.txt files though, which are in the *core* modules/ and themes/ directory and say basically "hey, buster don't put stuff here." That's no longer relevant when the top-level directories are the ones you should put your custom stuff into, as it will be after this patch. :) So those files in the core/ sub-directories can/should be removed.
Comment #14
aspilicious CreditAttribution: aspilicious commentedI'm totally in for this. :D
Comment #15
sunRTBC? :)
Comment #16
webchickCan someone step through a D7 -> D8 upgrade path with some contributed modules/themes and see how that goes first?
Comment #17
Crell CreditAttribution: Crell commentedThis is going to be a huge pain for people managing multiple sites on different versions. The drush maintainers will probably kill you. I admit I'm not the "target audience" for this issue, but I've never really had a problem with /sites/ confusing me when building single-site installs.
(Although, disclaimer, I'm the one who added sites/all in the first place back in Drupal 5. :-) )
Comment #18
Grayside CreditAttribution: Grayside commentedQuick reaction..
mv sites elsewhere
. Good for upgrades and backups.of multisite when possible to avoids the mini migrations of, say, later APC optimization.
Comment #19
sunre: #16: @webchick:
I can't think of any upgrade path failures due to this change. This is way less invasive than the /core directory change, and we're even able to handle that. ;) That is, especially because you ought to disable contributed modules in a major core upgrade... So, if there happen to be any issues, those are caused by something else.
re: #17: @Crell:
I don't see how this makes the situation any worse with regard to maintaining multiple major versions... the /core directory change is already in, which is the change that is truly troublesome. The entire point is that (novice) developers (mistakenly) [ab]used /modules for non-core modules in the past. Given that this [ab]use is even supported in D7, there's no real change here - /modules is still /modules, just no longer abusable — the only "real" change is the deprecation/removal of
sites/all/modules
, which just simply no longer makes sense, if you have a top-level/modules
already.That said, I'm perfectly aware that this change kinda leaves a "stray"
/sites/default
behind. However, @quicksketch already raised the idea elsewhere of whether we couldn't also move settings.php to the top-level (or alternatively, have a single/site
directory — which sorta reminds of Symfony's/web
and/or/Resources
directory, in case that is an argument ;) ).In the end though, this change makes Drupal site building much more easy to understand for newcomers, who have no interest in learning Drupal's multi-site capabilities, but instead want to understand how they can build Drupal sites.
re: #18: @Grayside:
You're making one good point there -
sites/all
allowed someone to easily move all modules/themes from the global directories into a different directory — be it for a major version upgrade path, or a delayed setup of multi-site functionality.However, given that the actual difference just means to execute 3 moves instead of one, and that both use-cases are quite advanced, I don't think they play a significant role here. (That said, for a major core upgrade, you only need to disable non-core modules, not move them.)
Comment #20
rafamd CreditAttribution: rafamd commentedThis change seems good for the not so experienced.
Leaving sites/default/settings.php behind doesn't sound that fine though. Easiest to find for beginners would be in the base directory, but I don't know if that's possible (permissions, etc ?)
What other uses are left for the /sites dir ?
Comment #21
pounardDoes this mean the sites/*/ will die? I have some multisites running, and it works very well, it's great a benefit when you have limited memory space for APC and such things.
Comment #22
mariomaric CreditAttribution: mariomaric commented@pounard: Hell no, just
sites/all/*
! :) Everything is explained in issue summary. :PIMHO, this issue could benefit from more visibility.
My 2 cents: after some thoughts, personally I'm against this. I think it's really nice that all core files are in
core/
folder, and having all site files sitting insites/[all|default|XYZ]
folder is consistent and convenient.I think it would be great to just add in
README.txt
file one extra paragraph:explaining structure of folders and what goes where.
IMO with moving only
sites/all/*
folders without touching rest ofsites/*
will only bring inconsistency and bad UX (user = site builder).Comment #23
sunNo, it just means that the directories in
sites/all/*
are moved to the top-level/root directory.The multi-site functionality is not touched at all by the proposed change here. However, you might be interested in #1055862: Require sites.php to opt-in for multi-site support/functionality
Comment #24
pounardOk, thanks.
Comment #25
klonos#562042: Search for install profiles in sites/[all|site]/profiles folders, and move core profiles into /core/profiles was recently fixed, but this issue here intents to move the /sites/[all|site]/* (including /sites/[all|site]/profiles) to the root of the directory structure.
I tried to understand from reading through this issue how the all vs. specific themes/modules/profiles will be separated once we implement this + #1055862: Require sites.php to opt-in for multi-site support/functionality but don't get it. Someone care to explain? Will it be:
/modules/all
/modules/specific-site
/themes/all
/themes/specific-site
/profiles/all
/profiles/specific-site
Comment #26
naxoc CreditAttribution: naxoc commented@klonos
As I understand it, the "all" folder concept is to be completely removed. So modules and themes should normally go in /modules or /themes directly. That way all sites can use it. If there is a specific site that wants to override a module it would go in sites/specific-site/modules.
Comment #27
klonos...ok so:
1. top-level modules/themes/profiles folders from D7 (that were used for core modules/themes/profiles) were moved under /core for D8.
2. sites/all/* were moved to top level, thus recreated the top-level modules/themes/profiles folders the were (re)moved in step 1 - only this time they'll be used for non-core modules/themes/profiles.
3. for site-specific modules/themes/profiles in D8 users will have to create themselves a sites/[site-name] directory (or will the D8 folder structure already include a "sites" top-level directory?) and place them there.
Right?
Comment #28
naxoc CreditAttribution: naxoc commented@klonos Yes, that is how I understand it.
More work on moving also settings.php to the drupal root is going on over at #760992: Where should site specific modules, themes and settings be kept?.
Comment #29
klonosThanx ;)
Comment #30
lpalgarvio CreditAttribution: lpalgarvio commentedi like it the way klonos described it.
a lot of documentation will have to be changed and some notices will have to be visible somewhere
Comment #31
sunCan we move forward here?
If there are still concerns about removing support for
sites/all/*
, then I'd suggest to just simply not remove that discovery path from drupal_system_listing() - but still create the new top-level directories for freshly installed sites. In essence, we don't really care and if some people findsites/all/*
more attractive than top-level directories for whatever reason in their custom setup, then they could happily use them.If that's what it takes to get this patch in, then I will happily do that minimal adjustment/revert to the patch.
Comment #32
lpalgarvio CreditAttribution: lpalgarvio commenteddon't forget Libraries dir during planing, as Libraries API might still get in time for core 8.
#667058: Add a libraries folder with a README.txt in it to DRUPAL_ROOT
#1167496: Libraries API in core
let me throw in some wood to the fire...
there has been in the past the discussion about using /contrib dir in place of /sites/all dir, as a solution that solves the problem underneath, but does not cause confusion (like the whole deal of /modules stated as "core alert, dont' hack" since old times) to current drupal users.
i'll revive it briefly, perhaps not with many arguments just yet, but instead with directory schematics:
current D8 scheme (/sites/all/*):
proposed change - plan A (/sites/all/* -> /*):
proposed change - plan B (/sites/all/* -> /contrib/*):
as you can see, plan B, might create a little more organization, clarity, simplify documentation... added to less confusion caused to old drupal users _and_ a clear correlation to contrib vs core vs user space.
Comment #33
sunLibraries are irrelevant for this issue. That's just another subdirectory next to modules/themes/profiles, regardless of where they are located.
Consider me -1 on adding a top-level /contrib directory. Not everything is "contrib", most sites also have a couple of custom modules.
You will still be able to differ between contrib and custom stuff, if you want to, by simply putting them into respective subdirectories; e.g.:
The discovery process does not care.
Let's keep this issue focused on sites/all/* » /*
Comment #34
webchickI'd rather kick the idea of a "contrib" directory to some other issue. That's a brand new idea, whereas this issue is about reshuffling what we already have.
Comment #35
lpalgarvio CreditAttribution: lpalgarvio commentedthe whole "contrib" name wasn't referring to whether modules/themes/profiles are contrib, custom, fell_from_the_sky or belong to a category like administration, but rather, they are non-core, and also, are not specific to sites (ie, /sites/all).
it's rather a placeholder name. could be something else, like "global", "non-core", etc. what i'm trying to sell is just a top-level directory that holds /modules, /profiles, /themes, etc in it, keeping things a little more organized and separate.
i don't think they belong in /sites, but since we are changing and perfecting things, right now i don't feel comfortable with having them in /, for the various reasons mentioned above, and for others...
like i might add, it's also easier and faster to do a
tar -zcvf contrib.tar.gz contrib
than doing a
tar -zcvf contrib.tar.gz libraries modules profiles themes
or a
tar -zcvf contrib.tar.gz --exclude=core --exclude=sites --exclude=index.php --exclude=robots.txt --exclude=.htaccess --exclude=web.config .
from an administrator/backup point of view
the hierarchy inside these directories is another whole issue that i wasn't trying to discuss here; i've done it before elsewhere ;)
Comment #36
sunI don't see why you'd want to tar all of your extensions without core. Your last command is factually wrong, because you still need to include /sites. In any case, if you want to do that, then you will have to care for excluding various stuff (or including the right stuff) either way.
Please, can we shift focus back to the actual proposal at hand?
The major benefit of having the directories at the top-level is that users are actually expecting them to be there. It improves the first-time user experience, because you do not have to step into various subdirectories in order to figure out where you should place the extensions you want to add. They're right there, KISS.
Comment #37
juan_g CreditAttribution: juan_g commentedsun wrote:
This seems a good, flexible compromise, so that site builders have more options to organize the file system the way they choose.
As suggested by others, other options like the recent proposal to group directories, could also be discussed and considered later in other issues for possible addition to drupal_system_listing.
Comment #38
webchickOk, let's do that then. Can we get an updated patch?
Comment #39
sunDone so :)
Comment #40
klonosI guess that once we have #1439316: Provide means for module maintainers to collect heuristics on certain settings of their modules. in place and enough time has passed so to have adequate data collected, we'll be able to see the percentage of people still using /sites/all. If that amount is trivial, then perhaps we can revisit this and remove the support for /sites/all/*. I guess we'll only want to do this for performance reasons - if that is an issue with that specific feature.
Comment #41
tim.plunkettI used the previous patch on a site for 2 weeks, and the new one still works as well, and is LESS controversial.
Comment #42
webchickOk great. I did a quick manual test to ensure that multisite was still working with this patch, and despite a derail based on my assumption that it picked up subdomains even though it does not... it still works. So yay!
Committed and pushed to 8.x. WOOHOO. This is going to need a change notice.
Comment #43
sunSlightly adjusting the issue title to avoid confusion. The committed patch did not, actually, "replace" /sites/all/*.
Comment #44
sunChange notice: http://drupal.org/node/1766160
Comment #45
plachAccording to the last paragraph of the change notice:
I think the D8 example is slightly misleading:
Should be something like:
Comment #46
sunSorry, yeah, stupid copy/paste error. Fixed it. Thanks! :)
Comment #47
lpalgarvio CreditAttribution: lpalgarvio commentedgreat =)
found an old related issue:
#1443420: About Drupal 8 directory structure
Comment #49
jwilson3A question came up about this change on #1539940: Encourage best practices in /sites/README.txt, /modules/README.txt, /profiles/README.txt and /themes/README.txt.
Specifically, how does this affect the other sub-directories in sites/all that haven't been mentioned (such as translations, libraries, drush, etc).
Comment #50
moshe weitzman CreditAttribution: moshe weitzman commentedgreat patch that i wish i was following at the time. i really think we should go all the way and remove sites/all from the discovery process. it does not simplify drupal to add new ways of doing stuff. you have to remove the old ones too. the only justification given here "so we can let site builders choose where to put their files". i think thats pretty weak relative to the added confusion of 'the modules could be here or there or there or ..."
i'm adding drush support for this patch and each directory scan takes time.
Comment #51
moshe weitzman CreditAttribution: moshe weitzman commentedWTF, I did not remove those tags.
Comment #52
jhodgdonRegarding #49, I did a bit more research...
- libraries are contrib-only so I think we shouldn't bother making a top-level directory for them.
- translations apparently don't belong in sites/all at all. See #1802322: Translation instructions are incomplete
Comment #53
rafamd CreditAttribution: rafamd commentedRE #50, true,
too manymore than one waysof doing the same thing confuses.Comment #54
pounard#50 And how about multisite? How will this work?
Comment #55
moshe weitzman CreditAttribution: moshe weitzman commented@pounard - the recommended place to put code thats shared across sites is now /modules, /themes, /profiles, etc. thats the whole point of this issue, which has been committed.
Comment #56
pounardho you mean that even multisite would share all, and there should be no way to provide different module versions on different sites? I never really used it except once, that's a very uncommon doing, but is that something we can do?
Comment #57
jhodgdonpounard: read the change notice on this issue (link is up in the summary section) -- it should answer all of your questions. sites/(site) is still available, as is sites/all.
Comment #58
pounardI was asking because #50 was suggesting i really think we should go all the way and remove sites/all from the discovery process and that's disturbing regarding multisite. Aside of that, I'm not against this issue, it's a fine feature to allow both top level instead of all and sites/SITE/*
Comment #59
Grayside CreditAttribution: Grayside commentedI read that as dropping sites/all, not dropping sites/{sitename}.
sites/all does allow for folks to easily create a standard recipe without going all the way into basic profile creation, but with tools like drush make I think that ground is reasonable well covered.
Comment #60
pounardOh my... ok I misunderstood what he said, sorry.
Comment #61
klonos@jhodgdon, #52:
...well there's #667058: Add a libraries folder with a README.txt in it to DRUPAL_ROOT
Comment #62
jwilson3Tagging, per #61.
Comment #62.0
jwilson3Updated issue summary.