Skip to content

Commit

Permalink
expose version release notes
Browse files Browse the repository at this point in the history
  • Loading branch information
@panoply
panoply committed Feb 17, 2023
1 parent b027a53 commit e752d63
Show file tree
Hide file tree
Showing 10 changed files with 923 additions and 1 deletion.
1 change: 0 additions & 1 deletion .gitignore
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,6 @@ node_modules
yarn.lock
test/components/*.html
versions
releases
docs
dist
example
Expand Down
27 changes: 27 additions & 0 deletions releases/readme.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
# Releases

This directory contains release notes and changelogs pertaining to each version of the extension. Versioning for this extension is not quite semantic but does borrow from the semantic foundations. Whenever a considerable amount of changes which require refactors by the end user result in a **major** version update.

The extension is currently in the version **4.x.x** range.

## v4.0.0 ~ Latest

The extension is currently shipping on version 4.

- [4.0.0](#)

## v3.0.0 ~ v3.2.2

Releases in version 3.0.0 ~ 3.2.0 shipped with breaking changes and had significant features made available throughout it's lifespan. These versions span several months in circulation, starting from September 28, 2022 and ending February 18th, 2023. Users who are still operating in version 3 should update as soon as possible as released in this version range are now considered broken and and unsafe for usage.

- [3.2.2](#)
- [3.2.1](#)
- [3.2.0](#)
- [3.1.0](#)
- [3.0.2](#)
- [3.0.1](#)
- [3.0.0](#)

## v1.0.0 ~ v2.3.0

Releases prior to **v3.0.0** can be found in the [v2.3.0 Changelog](https://github.com/panoply/vscode-liquid/blob/v2.3.0/CHANGELOG.md) branch. If you are still operating on versions in this range it is highly recommended that you update to the latest version releases.
337 changes: 337 additions & 0 deletions releases/v3/3.0.0.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,337 @@
<h1>v3.0.0^ ~ vscode-liquid</h1>

This is a well overdue update. While most issues were planned to be addressed in Liquify, it was apparent that **v2.3.0** was in dire need of an update. This version aims to fix the outstanding issues (most of which) pertained to formatting and have persisted for too long.

_After you have addressed the breaking changes, take a look at the [readme](https://github.com/panoply/vscode-liquid) in the project._

## BREAKING CHANGES

This version ships **breaking changes** and users will need to update and align in order to continue using the extension. The changes require you to replace workspace/user settings and/or configuration defined in the `.liquidrc` file (if you are using a `.liquidrc` file). Upgrading to the new version for the vast majority of users is a matter of copy and paste.

#### CHANGES YOU NEED TO MAKE:

- [The new `.liquidrc` file configuration](#the-new-liquidrc-file-configuration)
- [The new Workspace/User Settings](#the-new-workspaceuser-settings)

#### CHANGES TO BE AWARE OF:

- [The `ignore` tags option is no longer supported](#the-ignore-tags-option-is-no-longer-supported)
- [The`associate` tags option is no longer supported](#theassociate-tags-option-is-no-longer-supported)
- [Removed Liquid syntax highlighting in TS, JSX and TSX](#removed-liquid-syntax-highlighting-in-ts-jsx-and-tsx)
- [Liquid in JS, CSS and SCSS files now require `.liquid` suffixed filenames](#liquid-in-js-css-and-scss-files-now-require-liquid-suffixed-filenames)
- [The formatting key-binding was removed](#the-formatting-key-binding-was-removed-75)

## The new `.liquidrc` file configuration

As of version **3.0.0** the old schema used in `.liquidrc` files is **no longer supported**. If you are using a `.liquidrc` file you will **need** to update the file and align it with the new formatting rules.

Below is the **new** defaults for the `.liquidrc` file:

```json
{
"ignore": [],
"crlf": false,
"commentIndent": true,
"endNewline": false,
"indentChar": " ",
"indentSize": 2,
"preserveComment": false,
"preserveLine": 2,
"wrap": 0,
"markup": {
"correct": false,
"commentNewline": false,
"attributeCasing": "preserve",
"attributeValues": "preserve",
"attributeSort": false,
"attributeSortList": [],
"forceAttribute": false,
"forceLeadAttribute": false,
"forceIndent": false,
"preserveText": false,
"preserveAttributes": false,
"selfCloseSpace": false,
"quoteConvert": "none"
},
"style": {
"correct": false,
"classPadding": false,
"noLeadZero": false,
"sortSelectors": false,
"sortProperties": false
},
"script": {
"correct": false,
"braceNewline": false,
"bracePadding": false,
"braceStyle": "none",
"braceAllman": false,
"caseSpace": false,
"inlineReturn": true,
"elseNewline": false,
"endComma": "never",
"arrayFormat": "default",
"objectIndent": "default",
"functionNameSpace": false,
"functionSpace": false,
"styleGuide": "none",
"ternaryLine": false,
"methodChain": 4,
"neverFlatten": false,
"noCaseIndent": false,
"noSemicolon": false,
"quoteConvert": "none"
},
"json": {
"arrayFormat": "default",
"braceAllman": false,
"bracePadding": false,
"objectIndent": "default"
}
}
```

## The new workspace/user settings

The **v2.3.0** workspace/user settings **will not work** and users need to align configuration to the new **v3.0.0** settings. The `liquid.rules` option is completely deprecated and the `liquid.format` option no longer accepts a _boolean_ type.

The **v3.0.0** settings are as follows:

```jsonc
{
// Deprecated v2.3.0 Settings
// "liquid.format": true,
// "liquid.rules": {},

// New v3.0.0 Settings
//
"liquid.engine": "shopify",
"liquid.config.baseUrl": ".",
"liquid.settings.target": "workspace",
"liquid.completion.tags": true,
"liquid.completion.objects": true,
"liquid.completion.filters": true,
"liquid.format.enable": true, // instead of "liquid.format": true,
"liquid.format.ignore": [],
"liquid.format.wrap": 0,
"liquid.format.indentSize": 2,
"liquid.format.endNewLine": false,
"liquid.format.commentIndent": false,
"liquid.format.preserveLine": 3,
"liquid.format.preserveComment": false,
"liquid.format.crlf": false,
"liquid.format.markup": {},
"liquid.format.script": {},
"liquid.format.style": {},
"liquid.format.json": {},
}
}
```

## The `ignore` tags option is no longer supported

In version **2.3.0** the extension provided an `ignore[]` option which could be used to define a set of either Liquid or HTML tags to have excluded (ignored) from formatting. In version **3.0.0** the `ignore[]` option is not used to ignore tags from formatting but instead the option is used to ignore files and directories.

A string list of relative _glob_ patterns is the new expected type:

<table>
<thead>
<tr>
<th align="center"><strong>.liquidrc rule file</strong></td>
<th align="center"><strong>workspace/user settings</strong></td>
</tr>
</thead>
<tr>
<td >

```jsonc
{
// New v3.0.0
//
// Option is used to ignore files/directories
//
"ignore": ["./dir/file-to-ignore.liquid", "./example/*"]

// Deprecated v2.3.0
//
// "ignore": [
// {
// "type": "liquid",
// "begin": "comment",
// "end": "endcomment"
// }
// ]
}
```

</td>
<td>

```jsonc
{
// New v3.0.0
//
// Option is used to ignore files/directories
//
"liquid.format.ignore": ["./dir/file-to-ignore.liquid", "./example/*"]

// Deprecated v2.3.0
//
// "liquid.rules.ignore": [
// {
// "type": "liquid",
// "begin": "comment",
// "end": "endcomment"
// }
// ]
}
```

</td>
</tr>
</table>

> **Note**
> When you wish to exclude/ignore tags from beautification you can do this using [Prettify Inline Control](https://github.com/panoply/prettify#inline-control) comments.
### Removed Liquid in HTML grammar injections

This release has removed grammar injections from HTML. This means that users no longer use HTML as the language identifier for Liquid files. HTML intellisense features like hovers and completions are preserved. After upgrading to v3.0.0 all `.liquid` extension files will be associated to the **Liquid** language identifier.

> **Note**
> Users leveraging the Shopify Liquid extension may need to make a decision on whether to continue using that alongside this extension.
### The`associate` tags option is no longer supported

The associated formatting option is deprecated and no longer supported. The new formatting capabilities provided by [Prettify](https://github.com/panoply/prettify) negate the need for such a feature and users who relied on this capability will need to wait until documentation is written for the _grammars_ option provided by Prettify.

### Removed Liquid syntax highlighting in TS, JSX and TSX

Liquid syntax highlighting within `.ts`, `.jsx` and `.tsx` files is no longer supported. This capability was experimental at the time it was appropriated. This feature also caused problems for many users who were not working exclusively with Liquid projects so it is both an appropriate and sensible decision to remove.

### Liquid in JS, CSS and SCSS files now require `.liquid` suffixed filenames

Syntax highlighting Liquid in JavaScript, CSS and SCSS now requires filenames to be suffixed with a `.liquid` extension in order for highlighting to be enabled. In version **2.3.0** syntax highlighting for Liquid in these languages was applied using injection grammars but it was not an ideal approach. Users who depend upon this feature will need to suffix the file names to apply highlighting.

- `.css` → `.css.liquid`
- `.scss` → `.scss.liquid`
- `.js` → `.js.liquid`

This change also impacts intellisense capabilities. In **2.3.0** intellisense capabilities were preserved in these languages along side Liquid but in this version **3.0.0** intellisense is not supported.

> **Note**
> In Liquify intellisense will work as expected but in this version and future versions until Liquify supersedes.
### The formatting key-binding was removed #75

The key-binding used in **v2.3.0** would overwrite the default key bindings of vscode and was very problematic. Invoking beautification using a key-binding now adhere to the default vscode formatting key map:

<h3>⇧ ⌥ F</h3>

`shift + alt + F`

_This requires the `editor.defaultFormatter` be set `sissel.shopify-liquid` on a per-language basis. See the [readme](https://github.com/panoply/vscode-liquid#setting-default-formatter) section on setting a default formatter._

# Completions

This version also ships a pre-release (Liquify) feature. Completions for Liquid Standard and Liquid Shopify are available and you can enable/disable these features using the following workspace/user settings:

```jsonc
{
"liquid.completions.tags": true,
"liquid.completions.filters": true,
"liquid.completions.objects": true
}
```

## Tag Completions

https://user-images.githubusercontent.com/7041324/192540349-f2895f12-b7e4-43df-bd8f-32ddded2302c.mov

## Object Completions

https://user-images.githubusercontent.com/7041324/192760204-b0775e58-8d7a-4f31-99c4-248b8ab704f0.mov

## Filter Completions

https://user-images.githubusercontent.com/7041324/192541665-669e652e-4864-41ef-8bd2-45f18aed01d7.mov

## JSON Template Completions

In Shopify themes, JSON templates and settings_schema files provide intellisense capabilities such as code completions, validations and hover descriptions.

https://user-images.githubusercontent.com/7041324/192542979-af281b10-e7d3-4731-a43e-ddf201bfcbd0.mov

## Additional new Features

This release also ships several new features that aim to provide a more integrated experience when working with Liquid in vscode. These new capabilities are optional and mainly geared towards Shopify Theme developers.

### Intellisense Supported Configuration

_The `.liquidrc` and configuration provided to user/workspace settings in vscode supports intellisense features. Completions, validations and descriptions which describe each option._

### Ignore Files/Directories

_You can now exclude files/directories from beautification. The `ignore` rule accepts a \_glob_ match pattern relative to your working root directory of paths that should be excluded from formatting.\_

### Extended Syntax Support

_This version also brings support for Liquid contained in JSON and YAML files. JSON support is applied using grammar injection so intellisense capabilities are preserved. YAML support is made available through file extension suffix (eg: `.yaml.liquid`)._

### Improved status bar item

_You will notice in this release that the status bar item no longer uses the "Liquid" label and instead the 💧 emoji is the primary point of reference._

### More informative Output logs

_Output logs now include formatting stats and other various informative information about operations taking place by the extension. This will help users better understand what is happening behind the scenes._

### Snippets character choices

_Snippets now employ a more refined approach when it comes to applying whitespace dashes `-` - In previous versions 2 identical snippets would be made available (one for whitespace and one without) but now you can determine this in the tab assertion, so a single snippet entry (much cleaner). Liquid filter snippets similar dashes will infer pipe characters using choice completions._

### Informative Output Logs

_The output log prints informative information about actions that have taken place_

<img width="1364" alt="Screenshot 2022-09-28 at 12 48 57" src="https://user-images.githubusercontent.com/7041324/192760706-37e9b448-942b-485a-b53b-2c179e9ffced.png">

# Fixes

Below is the list of issues that have been resolved in this update. Thanks to all developers who submitted issues and I apologize it took this long to apply an update.

| Issue | Title | Submitted |
| ----- | ----------------------------------------------------------------------- | ------------------------ |
| #33 | **Formatting issues** | @davidpanzarella |
| #35 | **Comments** | @entozoon |
| #37 | **Markdown horizontal rule gets highlighted as if it were frontmatter** | @paulozoom |
| #38 | **Inline JSON gets messed up** | @lmartins |
| #39 | **Comments with Quotes Cause Strange HTML Injection** | @entozoon |
| #49 | **Respect editor settings or allow using tabs** | @passcod |
| #50 | **Formatting splits td tags** | @MiBuena |
| #52 | **Extension should only affect liquid tags** | @aes421 |
| #57 | **front matter in scss** | @irik77587 |
| #60 | **Snippet for checkbox setting has invalid default value** | @larsschellhas |
| #62 | **Highlighting does not work** | @jarkin13 |
| #64 | **Formatter changes single quotation to double quotation** | @renestalder |
| #71 | **Closing braces of a liquid object** | @endepointe |
| #73 | **Formatter isn't handling style well** | @james0r |
| #75 | **Format key binding conflicts with default key binding on Mac** | @ktnyt |
| #79 | **Formatting breaks json-ld script blocks** | @DPangerl |
| #83 | **assign variables breaks into new lines** | @mau2099 |
| #84 | **Syntax highlighting in yaml files** | @benjaminbosko |
| #86 | **Weird schema formatting** | @Weird schema formatting |
| #89 | **Force-attribute for 2+ attributes for HTML in .liquidrc** | @james0r |
| #96 | **vscode liquid format on save adds new tabs** | @itszoose |

# What about Liquify?

Liquify is still in development and in last few days I have had some communication with Shopify relating to the project. As per _Liquify and the future of this extension_ (#56) the project has been a very big undertaking and (currently) the codebase consists of nearly 100k lines spanning across 15 different modules.

Writing parsers and building out lexers is both a challenging and time consuming task and with each advancement you tend to introduce more possibilities and thus more time and deliberation.

In the last few months I got around to shipping a pre-release of [Prettify](https://github.com/panoply/prettify). Prettify is the beautification tool that Liquify will run atop of and it is now used in this version of the extension (so please report defects or issues!). Prettify alone took the better part of 6 months to refine and overhaul as it was adapted from the late Sparser and PrettyDiff projects that were being used in this extension up until **v2.3.0**. Liquify is still very much alive but albeit a tad cryogenic.

Join the [Liquify Discord](https://discord.gg/eUNEsxMuWt)

@panoply
15 changes: 15 additions & 0 deletions releases/v3/3.0.1.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
# v3.0.1 ~ vscode-liquid

This is a patch release version. As per #100 the defaults applied that automatically set `editor.formatOnSave` to Liquid CSS, Liquid SCSS and Liquid JavaScript are now opt-in. This prevents the extension form running unexpectedly on folks workspaces which have upgraded but not read documentation of release notes.

## Notes

### Frontmatter

The initial release did not support frontmatter during beautification. Prettify does not yet support frontmatter beautification so triple dashed delimiter regions are ignored by default until support is made possible.

### Fixed JSON inherited Rules

JSON rules were not being applied correctly, this patch also fixes that.

@panoply
3 changes: 3 additions & 0 deletions releases/v3/3.0.2.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# v3.0.2 ~ vscode-liquid

This is a patch release version. As per [#102](https://github.com/panoply/vscode-liquid/issues/102) which fixes and shortcut command `cmd + /` to create a liquid comments.
Loading

0 comments on commit e752d63

Please sign in to comment.