chore: pre-release checklist

[jonschlinkert]

• port remaining Ruby filters to javascript
• create all of the filters mentioned in the Shopify docs (docs are in markdown here, for easy access)
• port Jekyll/Liquid "tags" to javascript (when possible and practical. these are similar to handlebars block helpers)
• get rid of most deps
• remove duplicate filters (I created a couple of different versions of some filters, so we can discuss which direction we want to go. We can continue with this pattern until we're ready to publish, then we can remove dupes).
• write unit tests for all filters

Tests

• https://github.com/Shopify/liquid/tree/master/performance
• https://github.com/Shopify/liquid/tree/master/test
• https://github.com/jekyll/jekyll/tree/master/test
• https://github.com/jekyll/jekyll/tree/master/features
• https://github.com/leizongmin/tinyliquid/tree/master/test

There are other javascript ports of liquid, we can probably get more tests and filters from those as well.

cc @tunnckoCore @doowb

[jonschlinkert]

@tunnckoCore how do you want to divide up the tasks? Do you want to do unit tests? Or convert filters? Or both?

Or we can each pick a few categories of filters to work on.

[tunnckoCore]

I can handle the tests and few categories.

We can continue with this pattern until we're ready to publish, then we can remove dupes

Ookey.

[jonschlinkert]

I can handle the tests and few categories.

Awesome! Let me know which categories you're going to do so I don't do the same ones. thanks!

[tunnckoCore]

The color and money ones.

[jonschlinkert]

sounds good!

[jonschlinkert]

@tunnckoCore if you remember, try to put the methods in alphabetical order so we can more easily scan for missing/duplicate filters. Not a big deal.

[tunnckoCore]

Yea, was thinking about that too. Btw, should we preserve the underscore naming? I don't think so, because we are in the JavaScript land and linters may signal errors if users follow camelcase or other convention.

[jonschlinkert]

Btw, should we preserve the underscore naming?

Yeah, let's keep the underscores. I know it sucks, I agree - I don't like them personally either. My main goal is to make it really easy for Jekyll users to switch to another framework. We can easily create aliases for those though.

Edit: also it will make it a lot easier for us to scan the filters on liquid libs and check for parity.

[jonschlinkert]

linters may signal errors if users follow camelcase or other convention.

We can figure this out before we publish. Maybe we'll create a "name mapper" for aliases, so we can use camelcase, but for now IMHO it will make this easier if we stick to the same names.

[jonschlinkert]

One more thing... I'm trying to make most of the filters generic, but there are a few that have options.hash in them, which is a handlebars syntax. The reason is that those were ported from liquid "tags", which are more like handlebars block helpers, and there is no good way to port those to single line helpers that are template-engine-agnostic. We need to figure out a good way to expose those, maybe on a block property, or tags or something, but for now it's something to think about.

[jonschlinkert]

@tunnckoCore I just pushed up. Hopefully you don't get any conflicts, I didn't touch tests or the filters you're working on (do you get notifications when someone pushes up to a repository you collaborate on?)

[tunnckoCore]

No, everything is good. I'm working on a branch too ;d

do you get notifications

Yea, it's not a problem to me, I always have tons of notif cuz I watch tons of repos.

[jonschlinkert]

K, here is an example of how I'm doing comments. Don't worry too much about these, I can edit:

/**
 * Truncate a string to the specified `length`, and append
 * it with an elipsis, `…`.
 *
 * ```html
 * {{ "<span>foo bar baz</span>" | ellipsis: 7 }}
 * <!-- Results in: 'foo bar…' -->
 * ```
 * @param  {String} str
 * @param  {Number} length The desired length of the returned string.
 * @param  {String} suffix (optional) Custom characters to append. Default is `…`.
 * @return {String} The truncated string.
 * @api public
 */

exports.ellipsis = (str, len, suffix) => {
  return isString(str) ? (exports.truncate(str, len) + (suffix || '…')) : '';
};

I'm debating whether or not we should do the code examples in the comments, or if we should do them separately in docs.

Several years ago I created a code comment linter that reported how many methods were undocumented and a few other useful stats. IMHO that might be a good solution here. I have something we can use if we want to go this route.

edit: it would be awesome if our docs had examples for several template engines, but comments like the following are just too verbose and hard to maintain:

/**
 * Pads the given string with another string until the resulting
 * string reaches the specified maxiumum length. The padding is
 * applied from the end (right) of the current string.
 *
 * ```js
 * <!-- Signature: string.pad_end(str, maxLength[, padString]) -->
 * Liquid:     {{ "Foo" | pad_end: 10, "0" }}
 * Handlebars: {{pad_end "Foo" 10 "0"}}
 * ejs:        <%= pad_end("Foo", 10, "0") %>
 * <!-- Results in: 'Foo0000000' -->
 * ```
 * @param {String} str
 * @param {String} maxLength
 * @param {String} padString
 * @return {String}
 * @api public
 */

I have an idea... I'll create another issue.

[tunnckoCore]

What about just using multiple @examples?

/**
 * Pads the given string with another string until the resulting
 * string reaches the specified maxiumum length. The padding is
 * applied from the end (right) of the current string.
 *
 * @example hbs
 * <h1>{{ pad_end "Foo" 10 "0" }}</h1>
 *
 * @example liquid
 * <h1>{{ "Foo" | pad_end: 10, "0" }}</h1>
 *
 * @example ejs
 * <h1><%= pad_end("Foo", 10, "0") %></h1>
 *
 * @param {String} str
 * @param {String} maxLength
 * @param {String} padString
 * @return {String}
 * @public
 */

It not looks that bath bad, both in code and in docs.

[jonschlinkert]

I’m not a big fan of that format. It’s based on javadoc and IMHO it looks messy.

…

Sent from my iPhone

On Nov 25, 2018, at 10:53 PM, Charlike Mike Reagent ***@***.***> wrote: What about just using multiple @examples? /** * Pads the given string with another string until the resulting * string reaches the specified maxiumum length. The padding is * applied from the end (right) of the current string. * * @example hbs * <h1>{{ pad_end "Foo" 10 "0" }}</h1> * * @example liquid * <h1>{{ "Foo" | pad_end: 10, "0" }}</h1> * * @example ejs * <h1><%= pad_end("Foo", 10, "0") %></h1> * * @param {String} str * @param {String} maxLength * @param {String} padString * @return {String} * @public */ — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub, or mute the thread.