Best way to publish for Meteor?

[splendido]

As you might know Meteor supports as one of its core features CSS files discovery/minification/uglyfication.

At the same time thanks to an additional core package called less the support is seamlessly extended to LESS files.

So we can say that CSS and LESS style files are both supported by default.

At this point we have one question to answer: what would be the best flavour to be used to publish the main semantic:ui package?

Lets consider it is likely that other packages will be published to let any developer chose her preferred way to include styles.

• semantic:ui-less
• semantic:ui-sass

could be other two secondary packages to be published to complete the offer.

We should also agree about the way to publish all packages whenever a new version of the UI will be released.
I strongly suggest to have an automated script that picks up the body text of the official new release (e.g. this) and then goes publishing package by package.

The approach @dandv is proposing seem like quite clever since it involves no source code duplication and paves the way also for automated testing.
Should we copy from him?

@jlukic, @lumatijev, @nooitaf, @dandv, your turn!

[splendido]

This very same discussion was somehow already started here

Comparing all previous attempts made to publish style packages could be a good thing to start with ;-)

[splendido]

@DerMambo originally proposed a semi-custom less import in his blog post Meteorjs and Twitter Bootstrap - The Right Way for which

• https://github.com/DerMambo/less-bootstrap-3
• https://github.com/DerMambo/less-fontawesome-4

were created

One problem with this approach at the moment is that the packages directory no more exists (unless you're using it for your own local packages...)

[splendido]

More recently @Nemo64 revised the customomization of less files import proposing

• https://atmospherejs.com/nemo64/bootstrap (repo here)

claiming inspiration from this repository which goes back to the approach presented by @DerMambo

@Nemo64 leverages a JSON file (which can be placed wherever inside your project) containing a list of boolean flags you can change to select which components to add.

At a glance, this latter approach might seems a bit more hacky but still, IMHO, deserves some investigation.

[splendido]

You'll see that what we're trying to do with this discussion could have larger borders...
In case a wide consensus on a particular method (pros/cons, discussion, agreement) will be reached, it could actually be proposed and followed for all other packages like Semantic-UI: bootstrap, fontawesome, foundation, ratchet, ionic, etc.

but perhaps I'm flying too much away ;-)

[dandv]

Agree with @nooitaf on this:

i would guess the meteor-way of doing this would be to create a package of every module/part

I also see this repo in which we're discussing now is a separate repo. If it's only used to track Meteor integration issues & discussion - great. I think the actual integration code, when ready, should go along with the Semantic UI code, in that repo, under a meteor directory. That way, one command would have access to the source files and could publish to multiple sources, including Atmosphere. In that repo, we can work on a meteor-integration branch. This has been my practice with d3, Font Awesome, Moment etc. and has worked well.

So, in that meteor directory (<-- see this sample), we can either:

1. (simple solution) have multiple package.js files: package-less.js, package-sass.js etc, adding various different files each. The publish.sh script will take a parameter, e.g. meteor/publish.sh sass, and copy the corresponding package-*.js file to the root of the project before running meteor publish.
2. (more complicated) Alternatively, @Nemo64's approach of using a JSON file could also work. package.js can read the JSON file easily, and we can configure the package name, version etc. that way. Ideally this process would be driven from the Gruntfile (which most projects use), or in this case apparently the gulpfile.
3. Bonus - does anyone know how to make a Grunt task/plugin to publish a Meteor package to Atmosphere?

[splendido]

@zimme proposed with this post to have a base package containing all .less.import files and implying the less package.

Adding this package to a project will be made available all source files to be possibly imported with a custom semantic.less file to be put under the client folder of the project.
This would let people not only chose which components to be imported but also let them the possibility to change values to base variables (allowing for theme-ing) and define mixins before the actual compilation to css.

At the same time other dependant packages could automatically import only single components as well as the whole offer. Names for these dependant packages should be:

• semantic:ui
• semantic:ui-accordion
• semantic:ui-button
• etc.

If this approach is fine for you all, we can start to setup things up and make the first tests to confirm its validity.

[splendido]

Meanwhile, lets keep an eye also on this discussion started by @awatson1978.

Any possible outcomes could be of interest also for this thread!

[splendido]

A problem we'll be probably facing is understand which is the best way to get the icon fonts served...

[splendido]

Hey @jlukic, may I ask which it the workflow you follow to publish a new release?

I'm going to try to integrate the publication for Meteor directly from your Gulp file (in case you're using).
Is this something you'd accept?
This way you'd publish also for Meteor with the very same command you usually type ;-)

...obviously from our side, we'll do our best to get it working and tested so not to have you bother with this process.

Let we know!

Edit: it's the second time i switch gulp/grunt, sorry I was looking at an old fork I had among my repos. Now it seems you switched to gulp, right?

[jlukic]

I use gulp release for automating deployment to the repos that house single components.

https://github.com/Semantic-Org/Semantic-UI/blob/master/gulpfile.js#L640,

I recommend creating a new task update meteor then adding to the run sequence here

We can use the GitHub API also used extensively in update git to update single component repos

[splendido]

Ok, thank you for the head up.

Yeah, I'd try to leverage the github API to automatically setup everything for Meteor publish under Semantic-UI-Meteor (this repository)!

For now I'd say it might be enough to get published one main package plus one for every component.
After this we might think about having something also for themes...

[splendido]

I'm going to start playing with this on this forked repo.
Once things will be starting to shape well I'll make a PR back...

[jlukic]

Be careful I can say from experience when doing git from command line, you might find that a mistake might ruin the commit history of many repos as once (for example committing merge conflicts), which can be a bit difficult to recover from.

Have we decided whether meteor will include LESS files? How exactly will the files be changed for meteor? Will each JS definition have to be replaced? What needs to be adjusted for javascript to fit in more smoothly with meteor development?

[splendido]

Be assured I'm not going to touch your repositories, only files under UI-Semantic-Meteor!
...but I'm trying to get familiar with gulp for now ;-)

I think LESS is the one agreed to be included.
for this we basically need a copy of the src folder picking up the default theme right?

...but probably a package with pure CSS will be faster to set up properly (basically simply picking up files and assets from the dist folder plus a custom pacakge.js which is slightly different from meteor)

Anyone interested in publishing also semantic:ui-css?

[splendido]

for the less files, the only change would be the path for assets.

For the JS I think there's nothing to change, even if I had a little weird experiences with it.
e.g. selects opening only at the first click and then stop, which I solved with event handlers written by-hand the meteor way like 'click': function(e, t){$(e.currentTarget).dropdown("toggle")}
...this should be investigated more?
@nooitaf, @lumatijev, have you had to change something within the JS?
I think it's only about copying the two folders components and theme from the dist folder right?

[nooitaf]

I never changed the JS, only hardcoded CSS-paths to images or fonts.

I learned the best way for using JS is to use callbacks. For example, Approve / Deny Callbacks for modals. Otherwise the function/position will be lost..
http://semantic-ui.com/modules/modal.html#/examples
nooitaf/meteor-semantic-ui#25 (comment)

The _site folder is your personal override folder. Themes are structured the same way. If just the user could somehow overwrite or make use of that folder? Or maybe reference it via javascript somehow?

[splendido]

About JS @kevohagan might have something to add about this ;-)

[lumatijev]

Agree with @nooitaf, only thing I changed was paths. JS is working as supposed.

semantic:ui-css can be published just to avoid adding less package for people that want "stock" Semantic UI experience and no customizing options.

[awatson1978]

I'm a rather big fan of Nemo64's approach using the JSON configuration file (rather than using static links). Add the ability for in-app .less files to find the resulting output, and I'd be very, very happy as an application developer.

As an app developer, I should be able to rename and refactor files with no hassle. Anything that breaks that is bad. Anything supporting it is good.

[zimme]

@zimme proposed with this post to have a base package containing all .less.import files and implying the less package.

I believe you misunderstood what I meant here.

What i proposed was a "base" package named semantic:ui which have a dependency on the less core package and uses semantic-ui's less source to make semantic-ui available to the general mass of meteorites. This package would then automagically compile the .less files from semantic-ui's source into css files used by the browsers.

Then I proposed we have a separate, more "advanced" package named semantic:ui-less which might have a WEAK dependency on semantic:ui (api.use('semantic:[email protected]', 'client', {weak: true});).
But thinking about it I don't really see the need for that.

semantic:ui-less would, instead of working like semantic:ui, have semantic-ui's source files renamed to *.import.less to make sure meteor's less package isn't automagically compiling them.

The user of semantic:ui-less would then have to manually import the .import.less files they want to use in their apps by doing this in their .less files of the app.

@import '/path/to/semantic:ui-less/definitions/reset.less';
@import 'path/to/semantic:ui-less/....';
...

... "use semantic-ui's mixins in their custom less code" ...

[awatson1978]

Am with you up until the @imports. We need to figure out a way to get rid off those imports. Will probably require another package and build plugin though.

[lumatijev]

Another rather crazy idea would be to make script that will add packages to meteor application based on .json file that contains list of desired components (true/false) values?

[zimme]

semantic-ui have a gulpfile that can be used to build a custom version of semantic-ui.

semantic:ui-custom - This package would export semantic.ui.custom.import.less which is by default the result of running gulp install with automatic/express option.

If the user would like to change the custom semantic-ui components they would run
gulp install in advanced mode, set output file to semantic.ui.custom.import.less and their custom version would be exported instead.

And to use they would just @import 'path/to/semantic.ui.custom.import.less';

[zimme]

Another rather crazy idea would be to make script that will add packages to meteor based on .json file that contains list of desired components (true/false) values?

Maybe the gulp script could use some file as input?

[lumatijev]

Not sure about using input file for gulp. But with script based solution we could also handle meteor add and meteor remove easily so you can configure your Semantic UI on the fly.

[lumatijev]

Also, we could cover themes and site customization part.

[splendido]

I'm working exactly on the gulp file to integrate the packages creation and publish.
I'll commit something here by tomorrow I guess...

@zimme I think we're saying the same thing! The only thing I put different was that, once there's a semantic:ui-less-src package (I'd avoid to use semantic:ui-less if you then have to do something else to get styled out of it...) the main package called semantic:ui could simply import from the other one hence permitting to get .import.less files automagically compiled.

semantic:ui could hence be made up of a single semantic-ui.less file which has all the needed @import inside, plus a strong dependency on semantic:ui-less-src.
But this was just to leverage another already existing package.
It would also be fine the way you're describing.

I'm also @awatson1978 about the need to have something to be used to influence packages configuration!
But up to now the approach by @NeMO84 is the most advanced one in this sense.
...the only problem? It allows you what to include, but then you get it already compiled with no chance to change source variables to customize your theme!
or am I missing something?

From another point of view using the package semantic:ui-less-src would need the developer to write his own semantic-ui.less file where from importing whatever her needs (might be all at once by importing a file called semantic-ui.import.less which we will take care to include among the ones into semantic:ui-less-src...)
...but on the good side her could change variables to specify a custom theme before the line with `@import somepath/semantic-ui.import.less

Actually we could also publish pre cooked package whith this exactly pattern implemented, but already overwriting stuff based on available themes.

• `semantic:ui-twitter-theme
• `semantic:ui-amazon-theme
• ...

The only problem with this my proposed workflow?
Dig into referencing files from inside a package actually included by other packages....

[jlukic]

@splendido

Definitions cant all be directly imported using less imports. They have to be compiled separately, see my comment here Semantic-Org/Semantic-UI#1294 (comment) LESS has really primitive variable scoping.

My question for you guys is, if we're not translating/adjusting the source files for meteor, why do we need a different repos at all? Can't we just use the single component repos and the main repo and just publish to atmosphere?

[zimme]

@jlukic from what I understand this repo is only for the work until we reach a decision on how to best publish semantic-ui to atmoshere and then it will work from the regular repo, hopfully automated with the gulpfile. =)

[jlukic]

Makes sense. 🎯

[zimme]

When it comes to the custom parts of semantic-ui I do believe a solution using the official build tools for semantic-ui would be great as there would be very little to no new documentation for the meteor part of semantic-ui.

Also the build tools are only needed to select the theme/components/font-size and so on. When that's decided and compiled the user would rely on the compiled css/js.

[splendido]

@zimme, let me say you're a genius! ;-)

I've just realized that the tasks I'm adding to the gulp file used by @jlukic can be used by everyone to get on their machine ready to use meteor packages.

The good news? The results depends on how you configure the build :-)

[splendido]

@jlukic the thing about publishing to Atmosphere is not so easy as you might be thinking of.
(or perhaps it's me thinking too much to the other side...)

What is needed is a package.js with some descriptions plus the listing of all files to be included (something like this section of one of my files...)

This won't be in conflict with the already existing package.json though it might pollute a little more the repositories...

Having separate folders for each published package on this repo could permit to have specific README.md files (which will be linked from Atmosphere) containing information about how to install/use with Meteor, possibly a different title (ending with, e.g. packaged for Meteor) and stuff like this.

I don't want to push towards this direction if you don't like it. I'm also happy to ear different proposals...

What I'm doing now for the new gulp tasks is adding some more templates here (actually in a meteor folder at the same level) to create one self contained folder for each package to be published under this repository.

I'll let you know when I have something committed to take some comments from you folks!

[jlukic]

Readme files are generated in the gulpfile for each component repo. It also regexes the release notes finding lines related to each component, then automatically creates individual release-notes.md for each repo. The same thing is done with the readme.

Updating this for each repo is as simple as updating this template file

[splendido]

Yeah, I'm on it...

But so you're saying we could try to put all together?
Don't you mind having a section about Meteor on them?
...it seems S-UI is not being developed specifically for Meteor (it's all the opposite I guess) so I would not risk to ask to take too much space for it being on the very same repo and README file...

Thoughts?

[splendido]

This PR seems to have now reached an agreement by the official maintainers.

If you look at the changes proposed for the README.md you'll se a section about Meteor which links to a separate meteor/README.md file.

Is this something you'd accept to have?

[jlukic]

Yep, I'm perfectly fine with a meteor/ directory for including package.js a meteor readme etc.

[splendido]

Good!
...I guess the package.js file would live better in the root folder (to reference other files without ../ but it is something I'll try to check) though

[splendido]

Ok, I did a simple test before proceeding too much on closed roads...

This package.js file

Package.describe({
  name: 'semantic:ui',
  summary: 'Semantic empowers designers and developers by creating a shared vocabulary for UI.',
  version: '1.0.1',
  git: 'git://github.com/Semantic-Org/Semantic-UI.git#1.0'
});

Package.onUse(function(api) {
  api.versionsFrom('1.0');
  api.addFiles([
    'dist/semantic.css',
    'dist/semantic.js',
    'dist/themes/default/assets/fonts/icons.eot',
    'dist/themes/default/assets/fonts/icons.otf',
    'dist/themes/default/assets/fonts/icons.svg',
    'dist/themes/default/assets/fonts/icons.ttf',
    'dist/themes/default/assets/fonts/icons.woff',
    'dist/themes/default/assets/images/flags.png',
  ], 'client');
});

put in the root folder of the Semantic-UI repo works just fine to serve the compiled css version.
Fonts paths are fine too...

Summing up: to serve CSS versions (both whole and components) it is enough to inject some package.js files into the main repo and into each component repo!
This can be simply done hooking into already existing gulp tasks and using one more template for the pacakge.js.

If we agree on names for these repos I'll go on with this as the first milestone.

Note: the above files includes no testing for meteor!

Getting packages with less files might be a bit more tedious ;-)

[splendido]

OT
@jlukic, am I wrong or repositories UI-flag and UI-icon are missing the assets?

[splendido]

with this commit I managed to add the package.js file into each component repository.

The road to publishing css packages is narrowing ;-)

[jlukic]

Flag is, but icon isn't. I'll fix.

https://github.com/Semantic-Org/UI-Icon/tree/master/assets/fonts

[splendido]

Oh, sorry, I was looking at the components folder you create with the task create repos: there are no assets copied there as far as could see. Then I checked the online repo for the flag and there was pn gimage: I thought it was the same also for the icon.

The thing is I can't find where do you copy them from inside the gulp.js file. Perhaps you copied them by hand at the first time?

[jlukic]

Yeah, i copied them by hand since there are only 2 components that use them currently and its a bit simpler.

[splendido]

Ok, up to know I've managed to create package.js files for the main repo and for each component's repo.

At the same time I've also added automatic copy of assets files into components' repo (obviously only required files and only for components needing assets...)

There's also a bit of testing for the main repo, but only checking whether assets files are correctly shipped...

I've also tested that linking repo folder as local package works fine! :-)

You can have a look at the direction I'm taking looking at this comparison

Let me know what do you think about this!

[jlukic]

This looks good splendido. The only thing I'm a bit worred about is hard coding individual component asset names in the build tools. This doesn't seem scalable for an (x) number component UI library.

[splendido]

Yeah, I can imagine. The only thing is we need to list every single file used by a meteor package.

For example this is the package.js file for the icon component:

Package.describe({
  name: 'semantic:ui-icon',
  summary: 'Semantic UI - Icon, Single component release of icon',
  version: '1.0.1',
  git: 'git://github.com/Semantic-Org/UI-Icon.git',
  //readme: 'git://github.com/Semantic-Org/UI-Icon/tree/master/meteor/README.md'
});

var where = 'client'; // Adds files only to the client

Package.onUse(function(api) {
  api.versionsFrom('1.0');

  api.addFiles([
    'icon.css',
    'assets/fonts/icons.eot',
    'assets/fonts/icons.otf',
    'assets/fonts/icons.svg',
    'assets/fonts/icons.ttf',
    'assets/fonts/icons.woff',
  ], where);
});

what would you suggest?

whit that hardcoded list of assets I was also able to create all component repos from scratch also copying correct assets files.
While you said you had to copy them by hand the first time...

[jlukic]

I'm going to repost this here to continue discussion in public venue

These are transcribed from Splendido on Slack

• about assets, if you don't wish to keep an hard coded list of per component assets, I could just check it there's an 'assets' folder inside component repos and list all the files there in

I think managing assets manually is fine. Very few components use them and very few update them. I appreciate the draw in automation here, but I think it will add another point of failure.

at this point (which is not the final integration status I'd aim to reach) we are anyhow ready to publish packages for Meteor, at least the one with compiled CSS: it's just a matter of confirming package names I guess...

• What package names need confirmation?

I'd like to integrate also tests. I saw you have a 'tests' folder but (since I'm not a web dev 😉 ) I wanted to ask you how you're running them and from there I'll see whether there is room to recycle them also for Meteor testing

• I wrote tests for 0.x using TravisCI, Karma as a test runner and Jasmine/Sinon. I haven't updated the test runner to work with Gulp, and the test coverage is certainly limited from the previous tests. I've somewhat abandoned the TDD mentality, it moves too slow, but have no issues with someone setting it back up again.

about less packages, you said you had some weird structure for variables since there little/weird inheritance available. Do you think we could have some (pre) compiling steps to get some less base to publish?

The issue with LESS is that the files need to be compiled individually and cannot all be imported into a single file (that is compiled).

Each ui element inherits (and modifies) values from some of the same files (like site.variables etc), and LESS doesn't know how to handle multiple inheritance, and insteads squishes it all into one global scope.

This is all well and fine in the scope of a single UI element, but with multiple UI elements each inheriting overriding and inheriting again new defaults, its too much for LESS to handle.

---

[splendido]

What package names need confirmation?

we previously said packages should be with less sources, but at the moment it seems a bit complicated to get direct integration for this.

If we publish now css packages, should semantic:ui be used as the name for the main packages which includes css files and not less sources?
The same applies to semantic:ui-<component> packages...

Also, would you mind installing Meteor (automatically) on your machine to run the publish script (still to be written...) you would you prefer someone else do this?
The meteor installation is done via

curl https://install.meteor.com/ | sh

and not all are happy with this...

[splendido]

Hello @jlukic,
I'm sorry for the huge late but I'm back now!

The good news is I was working on a new project to facilitate 3rd party library integration into Meteor Packaging system.
You can find it at http://autopublish.meteor.com/
...guess what the UI is done with? ;-)

I think I'm going to prepare the final PR for the meteor integration by tomorrow.
The only thing we need at this point is keeping a package.js file up to date at every new release.

...for the components' assets listing I'll revert to a normal file listing on the component's repo supposing all assets files are already there.

In order to be able to complete all this, I still need an agreement on the final name to be used for publishing. The allowed form is:

organization-name:package-name

for the organization part we have all these already reserved by @dandv:

• semantic
• semanticui
• semanticorg

for the package name we can do whatever we wish (special chars cannot be used, but the -)

I'm for semantic:ui, but you (or someone else) might prefer semanticorg:semantic-ui.
What do you think @nooitaf, @zimme, @lumatijev, @awatson1978, @dandv, and all @Semantic-Org/meteor guys?

Btw, @jlukic after accepting the PR, all you'll have to do is head to http://autopublish.meteor.com/ and enable Semantic-UI and all component repositories for autopublish.
How this works is explained here but basically, by enabling a repo, a webhook is created for that repo to notify autopublish.meteor.com at every new release. Nothing else!

Would you accept this?
Or do you feel it might be too much intruding inot the repo?
...we feel this is far more acceptable than having to install meteor on your own machine to be able to publish or to have some random bash script put inside the repo to be run to get the package published.

I really hope you'll like the idea and jump with us on this great project!

[splendido]

Hei @jlukic,
I've just created the PR.

The text is quite general and does not make references to all the previous discussions we already had: this was purposely done to be later used as an example for other similar PRs.
I hope you'll understand... ;-)

For now I'm supposing we're going to publish under the name semantic:ui, but I'll be happy to update the PR according to what we agree on.

Let me know if you're fine with all this, or if you wish to change something.
After this I'll actually publish the current version (this is also wrongly stated inside the PR's text)...

Then we'll have to enable on autopublish.meteor.com also all components' repositories (in case you're still keeping them up to date: they're left back to version 1.4.1 at the moment...), but this will come later on (we need them to already contain a package.js file to be recognized as meteor packages...).

Let we know!

[MattiSG]

@splendido Can you confirm this is closed because it was fixed in Semantic-Org/Semantic-UI#1607? :)

[splendido]

,,,woops sorry, I wanted to link to the current thread but I forgot to :(

lets follow the continue of this discussion here

Btw, at the moment all CSS packages are automatically published and are working good!
The only thing left to final glowing is the semantic:ui package, supposed to provide a customizable LESS version of SUI