Understrap: What's the difference between understrap/sass/* and understap/src/sass/*?

[jonnymaceachern]

Issue is about..

• [ ] a Bug Report
• [ ] a Feature Request
• [ ] a Suggestion
• [x] a Question
• [ ] I need help

---

Other comments

What's the difference between understrap/sass/* and understap/src/sass/*?

I initially assumed that /src/ was a vendor folder (for third-party assets that were meant to be untouched), but then I saw that /src/js/ included a custom-javascript.js script.

Wouldn't it make more sense to keep all sass in a single folder?

[ZacharyElkins]

Explaination

understap/src/sass/ is a vendor and asset folder. It is populated mainly by Bootstrap files that the gulp task copies over. You'll also see FontAwesome and Underscores, both are assets that the theme uses but aren't built by the theme authors. So it does make a lot of sense to separate these files from the user's SCSS files and the ones that are custom built for Understrap.

I agree that the custom JS file is out of place. It was added after-the-fact and putting it there was actually the simplest way to do it. It will need to be reevaluated, as it doesn't really have a place.

Example

If we put it in understrap/js it would be inappropriate.
If we put it in understrap/sass it would be inappropriate.

Possible Solutions

So then the file needs its own directory to signify what it is: a js file that is for the user's custom code and is added to the main JS file by gulp scripts.

To me, the most sensible idea is having a whole separate folder added that signifies user code for styles and scripts. So, just like we have a src folder, we could have a folder that is for user js/css. This would make sense if we renamed src to assets and then used src for the user code, but might be confusing to previous users. We are then left with naming it user, custom, code, etc... and moving the sass folder there along with the custom js file.

TL;DR

understap/src/sass/

Assets from other projects, typically copied over during the gulp copy-assets process.

understap/sass/

User and theme custom SCSS files, as well as containing files to import in the vendor SCSS files from the src/sass folder. These can be customized to remove unneeded CSS, making it appropriate for the custom folder.

[davidshq]

I like the idea of using custom for the folder containing all code custom to an individual/organizational implementation of understrap.

...I also think it might be worth renaming src to assets or vendor or something other than src even without it conflicting (if custom is used) with the custom code folder...imho, this better elucidates the contents of the folder.

[Thomas-A-Reinert]

First of all: I totally agree that we should reorganize/streamline the whole thing a LOT.

Second: It works as it is atm. I heard no-one comply about the above mentioned facts almost anytime.

Third: It´s not OUR project. Well, yes it kinda IS. But @holger1411 is the project maintainer and I haven´t heard anything from/about him in MONTHS now. But I guess he had a reason to handle things like they are. Will try to contact him. If he won´t reach back, it´s maybe time for a fork.
(Sidenote: Just tried to contact him and received an automated notice that he´ll be back from vacation on 07.01.2018. So I hope I´ll get a notice within no time)

To weigh in my 2cents for any notices/suggestions:

What's the difference between understrap/sass/* and understap/src/sass/*?
this is totally un-elegant. Anyway, the npm-package - FOR WHATEVER REASON I WILL NEVER EVER UNDERSTAND - is named understap as far as I know. This SHOULD be fixed. But I can´t afaik.

but then I saw that /src/js/ included a custom-javascript.js
this also doesn´t make any sense at all. Call me in for being the initiator of that to have the need for a custom JS-file. It´s placement doesn´t make any sense though. Agreed. It HAS TO have a more "intuitive" path.

Wouldn't it make more sense to keep all sass in a single folder?
Yeap. Nope.
Bootstrap and underscores are the core of this theme. And UnderStrap itself overwrites a LOT of that on it´s own. So.. Performance-wise - a lot could be improved. Because we´re overwriting stuff. Resulting in more - unneccessary - CSS. But please understand: There´s a certain limit of what we can handle. We´d LOVE to be picture-perfect and totally abundant of any bloat - but that´s just not possible with the current config and a LOT of man-power!

As a resumee: I´m personally good to go with the overhead. And if you know how to tame UnderStrap (by e.g. commenting the core BS inclusions you don´t need etc.) you´ll nearly have no overhead from BS or US anyway. But yes, that needs a certain learning-curve/experience or call-it-whatever-you-like. I´m with UnderStrap since like 2014 or something and grew up with any of its flaws. Trying to see it from a user-perspective, I partially agree. There ARE things that can be improved and therefore i´m super-thankful for your input!

understap/src/sass/ is a vendor and asset folder.

Nope. This is just a vendor folder. You´ll never have to fiddle anything within that folder.
You´ll mingle within sass/understrap or sass/theme - however, I´d leave (in 90%) of all cases - sass/understrap untouched.
Reason. From what I understand from the npm/gulp-tasks sass/understrap CAN be overwritten with a npm install or update. And that sucks, too. ANY file that COULD be overwritten - by whatever - should be kept out of any "_usually used directories that may be used by devs to overwrite whatever_".

To me, the most sensible idea is having a whole separate folder added that signifies user code for styles and scripts.

Totally agree. My opinion.

• Use "SRC" for ANYTHING that gets included via npm installation or whatever.
• Use "assets" for ANY deliverables that _REALLY_ get served by the theme. So I´m TOTALLY against what @davidshq says like:

.I also think it might be worth renaming src to assets or vendor

Nope: "./assets" are deliverables by almost ANY thing I know in the Open-Source-Scene. I´d even love to put CSS/JS/FONTS into THIS folder. Got me? Following that guideline we could reduce the number of UnderStrap-folders a good bit.

But yes, it´d be good to good to improve the general structure and make it more transparent which files can be easily changed to reflect what the project maintainer (aka the theme developer) wanted to achieve.

I - personally - do not want to have any game-changers. And anything that will make the previous version incompatible with the upcoming. Recent improvements (really, they were!) F*cked up my dev-workflow. And that´s a bummer.
Keeping the whole thing:

• backwards-compatible
• measurable (in case of: How-far-does-it-improve-the-whole-situation!!)
• non-blocking
  etc. Is well .. challenging?

Not a challenge, we´re not generally willing to accept BUT..

• nothing we´ll realize in the next two weeks (NO! maybe not within the next 6 months!)
• and nothing we´ll develop on the main-branch.

In any way, @davidshq - thanks for your input. Just wanted to spend 10 mins max for your issue, but It got me more involved than I planned / wanted / tought.

+1 for you. We´ll discuss that in our project-thingie.. :)

Anyway: I´ll close that topic. Everything discussable seems to have been discussed so far. I guess your intention has been followed, too. If you have any question etc. - please leave a follow up.
I just want it to get out of the "ISSUE" tracker, okay?

[axlright]

Thanks for thinking about all this @Thomas-A-Reinert .

the npm-package - FOR WHATEVER REASON I WILL NEVER EVER UNDERSTAND - is named understap as far as I know.

I've wondered about this as well. I thought for a while it was like the difference between npm i underscores https://www.npmjs.com/package/underscores and npm i undescores-for-npm https://www.npmjs.com/package/undescores-for-npm (the second one being off by one letter) which is maybe due to someone else having already made an npm package. But I don't know why the npm package is called undescores except because if a misspelling.