changemewtf commented 9 years ago

I'm confused by these files being included in the default .gitignore that appears after running gulp for the first time. I kind of understand dist since it is generated locally by the gulp watch process, but aren't src/site, theme.config and semantic.json used as part of that very build process?

jlukic commented 9 years ago

Yes but they contain a local user's settings and shouldn't be modified by upstream changes from SUI.

changemewtf commented 9 years ago

Yes, but if I tell gulp to "remove setup files", the intention is for the current folder to now represent only the files necessary for my unique installation and continued usage of Semantic, right? So if I'm collaborating on my project with colleagues, I would certainly want them to receive updates when I make changes to our project-local themes.

jlukic commented 9 years ago

The maintainer of the lib has uses the same build tools to build dist as you, so the .gitignore makes sure those files aren't published to the repo as a maintainer updates files.

It's easy enough to modify, if you are using a forked version.

Steveb-p commented 9 years ago

If you really need to put src files under version control for collaboration with others without forking, then you might either create a new repository inside src folder (just git init/clone into it) and provide it as standalone repository, or specify more detailed path during gulp install. Forking is however prefered. Then you can force add them to repository (git add -f as I recall)

changemewtf commented 9 years ago

If everyone is using the same build tools, it seems inefficient to optimize them for the maintainer's usage and assume that everyone else will figure out which pieces are necessary just for implementation.

If customization and theming are first-class supported features of Semantic, then it should be possible to use standard source control practices with them, without having to override a prefab .gitignore file or maintain a forked repo. No other JS/CSS frameworks that I am aware of require this, and if it is truly necessary for Semantic to do so, it should be explicitly documented.

Right now, there is very little clarity or documentation to laydevelopers in terms of which files are important and how they are used. Automatically adding site-specific files to .gitignore sends an erroneous signal that these files are not significant, which is a very confusing distraction.

martindale commented 9 years ago

+1 on being able to maintain customizations without maintaining a separate, forked version of Semantic.

There does not appear to be a way to simply utilize the LESS files without tightly coupling with Bower, which handles the overrides, themes, and so on – while the Semantic build tools are fantastic, getting Semantic itself integrated into a project should not be so infectious, but should rather play nice with other directory structures and deployment strategies.

jlukic commented 9 years ago

If anyone has any specific suggestions on how to move forward, I'm listening.

changemewtf commented 9 years ago

1: Is all component code included in the compiled distributables?

Am I correct in thinking that the compiled semantic.{js,css} files contain 100% of required JS and CSS, including everything from the dist/components folders?

If so, would it make sense to have a build option that outputs only those files + minified to a specified directory? I'm actually a little unclear on why dist/components exists at all if the component code is indeed included in the compiled semantic.{js,css} files.

2: What are the actual required files?

Also, am I correct in thinking that these are the files (and the only files) required for a fully-functional implementation using the default theme?:

semantic.js
semantic.css
default/assets/fonts/icons.woff
default/assets/images/flags.png

3: Clarifying "site source", "semantic source", and "dist"

I'm not sure why src/_site exists as opposed to just calling it src/site in the first place, and thinking of that as the "default" site source for the vanilla distributable. Same deal with semantic.json.example and theme.config.example: Why not just call them semantic.json and theme.config? Just trying to get a sense of why things are set up the way they are so I can give more meaningful suggestions/feedback.

jlukic commented 9 years ago

1. The compiled releases contain all components by default

Semantic will continue to grow in scope, which means a concatenated release with all components will get larger and larger. Unless you can run the build tools to produce your own semantic.js it will contain sidebar for sites with no sidebars etc. which will reduce performance due to unused css selectors still having to be parsed.

2 Depending on your implementation you may want to use dist/components/ or semantic.{js,css}.

3. The reason semantic.json.example, theme.config.example and _site exist is to prevent updates from overwriting your site's theme and configuration. This is a similar process drupal, wordpress and other frameworks use to get people set up with theming.

jlukic commented 9 years ago

I can see whydist/ should not have been in the .gitignore. I'm removing it now.

Perhaps I can just use (and ask all other contributors) to use something like git update-index --assume-unchanged src/site which is functionally equivalent to .gitignore. I need to mull this over a bit.

recipher commented 9 years ago

I can more or less see how this all works. I'm trying to work out how to integrate the build/customisation process into my build process though.

At the moment, I've just bower install-ed into my site. I'm using Gulp to build my vendor JS and CSS and it uses the main property in bower.json to decide what to build.

I'm making customisations by overriding in my SCSS files.

If I want a custom installation of Semantic (and I will, once I lock down which components I'm using), then I can do this:

fork semantic git clone semantic-fork install make customisations build git push to the fork update the bower file in the site to use the fork

So, if I do that, when we need to pull changes from the main semantic repo, we just pull from that remote.

That seems like a reasonable process to me. Have I missed anything? Is that the intended process? What's the problem with doing it that way?

On 3 December 2014 at 23:08, Jack Lukic notifications@github.com wrote:

I can see whydist/ should not have been in the .gitignore.

Perhaps I can just use (and ask all other contributors) to use something like git update-index --assume-unchanged src/site which is functionally equivalent to .gitignore. I need to mull this over a bit.

— Reply to this email directly or view it on GitHub https://github.com/Semantic-Org/Semantic-UI/issues/1350#issuecomment-65508923 .

chanon commented 9 years ago

Hi, I also have issues / don't like how Semantic-UI's .gitignores and build system folders are setup as I think it is somewhat rigid and a bit hard to adapt to different setups.

I strongly agree with @mcantor comment: https://github.com/Semantic-Org/Semantic-UI/issues/1350#issuecomment-65251696 and @martindale comment https://github.com/Semantic-Org/Semantic-UI/issues/1350#issuecomment-65361154

There are two main issues that I have: (I'm a node developer who uses npm to install semantic-ui.)

1.

I like how it is possible to build a semantic.min.css and sematic.min.js that includes only the components that I decide to use.

However since I'm using webpack to package js, jsx, less and css files already, I would rather have webpack handle the building/minification in one step by directly requiring/importing the sematic-ui js and less files that I actually use.

Ideally, how it would work with webpack is, for example if one of my jsx components used the checkbox module, then I'd just:

// at head of my jsx file, require the js and less files
// (this is how webpack works)
require('semantic-ui/src/definitions/modules/checkbox.js');
require('semantic-ui/src/definitions/modules/checkbox.less');

// maybe I use another element definition
require('semantic-ui/src/definitions/elements/list.less');

// I could also use less's import statement in one of my own less files instead
// actually, that might be the required use so that the global less variables are still accessible

// the rest of my jsx code

I do this in all my jsx modules, then when webpack does its packaging, it will go through all require statements and package all js/jsx files to a single minified js and less/css files to a single minified css (or it could also be included in the minified js, depending on how webpack is configured.)

In this way, I wouldn't have to do any bookkeeping to keep track of which modules/elements I actually use, I just use them and they are packaged/minified by webpack. Additionally, with webpack's hot reloading, I'd be able to modify my semantic-ui site customization overrides/variables file and see changes without needing to refresh my browser.

I tried doing exactly this (tried both referencing less files using require and using import in my less files), but what happens is there are errors due to some undefined less variables that seem to be generated and exist only during the build process,

So instead I have to first note which modules I use or not, update the semantic.json file, and then run semantic-ui's build script .. which is somehwat inconvenient which discourages me from actually using the site overrides/variables files or taking out too many components from semantic.json. I just leave most of the components in there in case I decide to use them in the future so I don't have to rebuild the semantic.min.js/css files too often .. defeating the purpose of it. And also overriding styles in my own less files is a lot quicker for tweaking.

I know semantic's build system has a watch feature, but for me it didn't catch some of the changes sometimes (ex. it doesn't catch semantic.json component changes) and webpack's hot reloading is a lot quicker anyways.

2.

I think it is weird and somewhat inconvenient having customized site variables/overrides live under node_modules/semantic-ui

There are the .gitignore issues mentioned above (maybe fixed .. I haven't updated to 1.1 yet), but usually for me whatever is in a node_modules/module_name folder is code managed by the module creators that I usually don't need to touch and don't usually need to worry about. Definitely not application code. If I lose anything in a node_modules module folder I can usually just npm install to install it again.

Additionally, the way npm works is it sometimes deletes the whole module folder when something goes wrong during installing/upgrading a module. So I'm somewhat worried having such important application design customizations in there.

I see that there are some settings that I can change to tell semantic where I want the different folders to be, but it seems they are too tightly coupled. I couldn't figure out how to put the site folder outside of node_modules while leaving the definitions / themes folder inside it.

Ideally I should be able to set where the site folder will be, and a folder for 'additional' themes (in addition to those in /node_modules/semantic-ui/src/themes) and leave the definitions and themes (which are the files that semantic-ui module developers provide) under node_modules. This way when there is a new semantic-ui version I can npm update semantic-ui without worrying about my application code.

Maybe this can already be done, but I couldn't figure it out or find a way to easily do it. (Documentation issue?) Additionally, I think having to specify a location for the site folder that is outside of node_modules should be the default/expected usage.

Having to fork my own branch of semantic-ui just to use it in its intended way is overkill in my opinion. I usually fork a node module (or most any open source project) only if I intend to contribute to its development or need to quickly patch a bug.

I know that it might be a bit hard to achieve both 1. and 2. at the same time. As 1. essentially says "I should be able to use semantic-ui less files directly without requiring to use the build system" and 2. says "I should be able to put the site folder wherever I want" which is something that might require the build system to handle. But maybe with some less magic / less config file, it could be possible? Worst case, there might need to be a gulp task to generate some less config files that help point where the site folder is - which would need to be run only once.

jlukic commented 9 years ago

@chanon

I agree that it's unreasonable and bad for a developer to maintain themes inside node_modules/

"I should be able to use semantic-ui less files directly without requiring to use the build system" and 2. says "I should be able to put the site folder wherever I want" which is something that might require the build system to handle. But maybe with some less magic / less config file, it could be possible? Worst case, there might need to be a gulp task to generate some less config files that help point where the site folder is - which would need to be run only once.

You're describing our build set-up. The paths for themes and site are set in semantic.json. I think the issue is most people just leave everything to default, which works well if you just drop the zip file in a folder, but works terribly with package managers where these files are impermanent and could be lost.

What I propose as a solution, is that the build process should detect if its currently in a bower_components or node_modules folder and set the default paths to escape the component folder, i.e. ../../ui/. It would then need to create the folder and copy over the theme files.

This would mean you would have to cd into the component directory once to run the install, but I think this is inevitable.

This is also a difficulty with gulp build and watch etc. It almost seems to make sense to have a CLI for everything that just runs the install/watch/build tasks from the component folder.

W/r/t integrating with existing build systems

LESS cant be directly imported because their inheritance system is very rudimentary #1294 so a build system of some sort is necessary (compiling each component individually)
I think the easiest way for existing systems is to build the component with semantic, then have your build system watch the output uncompressed source dist/components and do something with those files.

Second off, and this is just a disclaimer for my sanity, but I mean no ill feelings. This is a project that is very large in scope. Maintaining bugs across 50 components, a translation team that's up to 120+ people, docs that are bordering on short novel length, and planned extensions of the library (theme site, layout site, etc) all make for a very full plate for a developer. MeteorJS may have $11 million in AZ funding to work on open source, but this is a project funded with a few hundred dollars of personal donations a month (from incredible, thoughtful people I might add).

I encourage anyone who sees a feature missing, or is angry about how something is implemented to work on a proposal for a change, and to help implement it. This is how open source works best.

changemewtf commented 9 years ago

No ill feelings taken at all, @jlukic! I really appreciate your quick and thorough followup on all of the issues I've been filing recently. Thanks very much for the hard work!

recipher commented 9 years ago

I'll love to be in a position to contribute, perhaps the AngularJS integration might be the best place. We'll see.

Your work is outstanding, I'm at something of a loss to understand how you've done it, frankly.

On 4 December 2014 at 18:20, Jack Lukic notifications@github.com wrote:

@chanon https://github.com/chanon

I agree that it's unreasonable and bad for a developer to maintain themes inside node_modules/

"I should be able to use semantic-ui less files directly without requiring to use the build system" and 2. says "I should be able to put the site folder wherever I want" which is something that might require the build system to handle. But maybe with some less magic / less config file, it could be possible? Worst case, there might need to be a gulp task to generate some less config files that help point where the site folder is - which would need to be run only once.

You're describing our build set-up. The paths for themes and site are set in semantic.json. I think the issue is most people just leave everything to default, which works well if you just drop the zip file in a folder, but works terribly with package managers where these files are impermanent and could be lost.

What I propose as a solution, is that the build process should detect if its currently in a `bower_components or node_modules folder and set the default paths to escape the component folder, i.e. ../../ui/. It would then create the folder and copy over the default theme.

This would mean you would have to cd into the component directory once to run the install, but I think this is inevitable.

This is also a difficulty with gulp build and `watch etc. It almost seems to make sense to have a CLI for everything that just runs the install/watch/build tasks from the component folder.

W/r/t integrating with existing build systems

LESS cant be directly imported because their inheritance system is very rudimentary #1294 https://github.com/Semantic-Org/Semantic-UI/issues/1294 so a build system of some sort is necessary (compiling each component individually)

I think the easiest way for existing systems is to build the component with semantic, then have your build system watch the output uncompressed source dist/components and do something with those files.

Second off, and this is just a disclaimer for my sanity, but I mean no ill feelings. This is a project that is very large in scope. Maintaining bugs across 50 components, a translation team that's up to 120+ people, docs that are bordering on short novel length, and planned extensions of the library (theme site, layout site, etc) all make for a very full plate for a developer. MeteorJS may have $11 million in AZ funding to work on open source, but this is a project funded with a few hundred dollars of personal donations a month.

I encourage anyone who sees a feature missing, or is angry about how something is implemented to work on a proposal for a change, and to help implement it. This is how open source works best.

— Reply to this email directly or view it on GitHub https://github.com/Semantic-Org/Semantic-UI/issues/1350#issuecomment-65677291 .

chanon commented 9 years ago

I agree. @jlukic your work is amazing. I'm extremely sorry if my post made you feel pressured. I really love semantic ui and its philosophy and greatly appreciate your work. I could never get into other css frameworks, semantic however just made sense immediately.

I think your described solution would be great. I'll try to help contribute where I can. Thank you!

jlukic commented 9 years ago

I've moved the discussion to a new thread with a proposal. I recommend continuing discussion in the new thread.

Semantic-Org / Semantic-UI

[Build] Restructuring Default Install #1350

1: Is all component code included in the compiled distributables?

2: What are the actual required files?

3: Clarifying "site source", "semantic source", and "dist"