ember-learn / deprecation-app Goto Github PK

View Code? Open in Web Editor NEW

22.0 22.0 69.0 51.55 MB

Deprecation guides for ember.js, ember-data, and ember-cli

Home Page: https://deprecations.emberjs.com/

JavaScript 38.84% HTML 2.68% SCSS 41.05% Handlebars 17.42%

ember emberjs hacktoberfest

deprecation-app's People

Contributors

Stargazers

Watchers

Forkers

hakilebara jaredgalanis amyrlam lupestro cibernox rondale-sc kennethlarsen dhaulagiri albertpak coleyb nummi sly7-7 s-chiriac simonihmig gaurav0 ppcano cafreeman chadhietala iamwebwiz deverstalmage ssutar backspace alonski rwjblue gitkrystan rajasegar herom1 nullvoxpopuli pete-the-pete richgt heroiceric kamalsharma1 hazdik gavinjoyce gokatz jeffhertzler bartocc chriskrycho vinodhrajamuralidharan cloke jamess-m neojp snewcomer jamescdavis patocallaghan bertdeblock rabbihasanr nlfurniss fozy81 himynameisjonas glarregle fannyvanrell shubham-y smilland camerondubas cvx janzenisaac harshith-venkatesh isabella232 mehulkchaudhari pinkdiamond1 arafatiqbal kategengler baltazore gtechsltn jahrock achambers briandouglasie

deprecation-app's Issues

Add padding on the right when a `title` is really long

When a title is really long, add padding to the RHS. This is in the TOC on the LHS.

Update the route and adapter to support querying the "collection" json

  path: 'ember-v2'
})

this.store.query('content', {
  path: 'ember-v1'
})

this.store.query('content', {
  path: 'ember-cli-v1'
})```

Serena: Id-checking

This is a WIP issue for me to check for all the ids:
Version 1:

v2:

#toc_use-notifypropertychange-instead-of-propertywillchange-and-propertydidchange
#toc_getting-the-each-property

Ember CLI v2

#toc_migrate-from-brocfile-js-to-ember-cli-build-js
#toc_deprecate-utility
#toc_base-url
#toc_clobbering-addon-options

Ember data v2

Explain "Deprecations added in Upcoming Features"

In https://emberjs.com/deprecations/v3.x/ the "Deprecations added in Upcoming Features" section needs additional explanation indicating that the deprecations under that section are meant to be shipped in future releases & that they'll be updated to mention the release they're introduced in as they land in ember or ember data.

The reasoning behind this is that at times certain features might be deprecated in non release channels but might take time to land in a main release, so in order to document them rfc implementors are expected to create a deprecation explanation ahead of time so that they deprecation urls will begin to function.

make sure that if an ID is defined in frontmatter it is used instead of the filename

This tells the serializer to use the "path" attribute as the ID https://github.com/stonecircle/broccoli-static-site-json/blob/master/index.js#L23

let's fix that in the code (e.g. https://github.com/stonecircle/broccoli-static-site-json/blob/master/index.js#L68 ) and it should "just work"™

Rendering bug when rendering contents of version 2.0

I came across a rendering bug when adding content for the deprecations with since set to 2.0, see screenshot.

The generated data only contains "since": 2,

@mansona Would you have any idea why it is rendering in this way and it cannot read the 2.0?

Make sure the code examples have at least got a dark background in the fastboot version

When you disable JS you should still be able to see the examples, even if they aren't highlighted correctly

implement "anchorable-toc"

Add "guides" search

The current live deprecations page has a search bar which gives results for the guides. Let's add the search component to have the same functionality on this new guides app

Deployment issues

The heroku ember.js buildpack builds this app with prember using ember-cli-deploy. After the build since it notices ember-cli-fastboot in dependencies it assumes that we'd like to serve it as one and starts a fastboot server. This behavior causes issues in our app. What we'd like is for it to just deploy it static mode using heroku static buildpack internally like it would if the fastboot dependency wasn't declared.

We could use the static buildpack instead of the emberjs buildpack. The problem is that we need a build step using the node build pack to let it know which directory to serve. The only hook that we're aware of atm we could use to do this is postinstall in package.json. This didn't work for us in our attempts.

Making the emberjs buildpack understand that this is a static app by looking up premberin app dependencies or using an env variable is one step towards making this work. We would additionally need for the buildpack to use our static.json which would define our error file to use, which is important for certain urls from the old app to work. This is a requirement to use this app with prember.

Alternatives are,

Remove prember temporarily and go live with fastboot mode. Least effort on infra site but needs testing of the app.
Temporarily use netlify but this is troublesome when it comes to managing apps.

We could temporarily go with either solutions to go live while we work with terrance from heroku to figure out how to solve this to have this hosted on heroku with prember.

support more than one type

Deprecations in Ember 1.x have also warnings, see https://www.emberjs.com/deprecations/v1.x/#toc_binding-style-attributes

Production and Staging deployment is not currently working

Howdy folks 👋

I'm creating an issue as a request of @sivakumar-kailasam to keep track of the deployment issues we're having with this new setup. I'll do my best to describe what we need/want and we can go from there.

The first thing is that @locks mentioned there was an error on the backend when you hit an endpoint

2018-02-19T12:04:04.450433+00:00 app[web.1]: Error: You are using Ember Data with no host defined in your adapter. This will attempt to use the host of the FastBoot request, which is not configured for the current host of this request. Please set the hostWhitelist property for in your environment.js. FastBoot Error: The host header did not match a hostWhitelist entry. Host header: deprecations-app-prod.herokuapp.com

This implies to me that fastboot is running this environment. Because of prember fastboot should not be running as part of this deployment at all. Everything is available as a static application. We should turn off fastboot for this application because it is not designed to work that way.

(edit - found the issue when describing it)

The issue is that we have now added the prefix of /deprecations/ to all of the URLs. When going to this url: https://deprecations-app-prod.herokuapp.com/deprecations/ember/v2.x we actually need to serve the index file in the /ember/v2.x folder. The simplest way to do this is to just make the ember app also prefix everything with /deprecations/ and to add that to the prember configuration. @sivakumar-kailasam let me know if you can solve this from a routing perspective but if not I would be inclined to fix it at the ember level 👍

Make the version and "sub-project" dynamic

You may want to look at how the guides-app uses dynamic versions: https://github.com/ember-learn/guides-app/blob/53ac08eafbcb1083fe748ece442349a2028d0853/app/router.js#L10

Add information about dealing with deprecations generally

Since we have an index page for deprecations, we should strive to utilize it better.
One thing we could add is generic information on how to deal with deprecations, and the various tools available.

These are more suggestions than requirements:

Deprecation guide for Deprecate Globals Resolver RFC

Deprecate Globals Resolver RFC: emberjs/rfcs#331

Here are some notes to help me create a deprecation guide.

This is not a full transition guide, just an overview
If you can, transition to ember-cli, most of the community uses it
What is deprecated
- Using the globals resolver (use ember-cli resolver instead)
- Creating a global namespace (just use a directory)
- Using Ember.TEMPLATES[] array (get template from new resolver)
- Placing a template directly in index.html (use template precompiler that comes with your Ember version)
To adapt your existing build tool and configuration
- link to repo of new resolver to extend from (https://github.com/ember-cli/ember-resolver)
- the resolver uses amdStrict module syntax rather than App.NameOfThingTypeOfThing
- ember-cli provides a nice system for building compatible AMD modules

Edit: I will attempt to draft this myself.

Add the tomsters

Implement the option 3 of https://codepen.io/melsumner/pen/jZadZJ/

@MelSumner Just one question, where this should live :)

On the main page, see screenshot

Or on the sub-domains per specific deprecation, e.g. https://www.emberjs.com/deprecations/v1.x

Port the new header/footer styles from the website

follow the lead of the guides-app and create {{main-header}} and {{main-footer}} template and separate CSS files: https://github.com/ember-learn/guides-app/tree/master/app/templates/components and https://github.com/ember-learn/guides-app/tree/master/app/styles

these new components will be copy&paste synced between deprecation-app and guides-app 👍

Cannot get the app to run anymore

I get the following error on master when running npm install:

Clean install, deleted node_modules folder

node -v
v8.4.0

npm -v
5.6.0

cc @mansona Send halp :)

Implement the table of contents

Add support for collections in broccoli-static-site-json

POC implementation:

new StaticSiteJson(`node_modules/@ember/guides-source/guides/`, {
  collections: [{
    src: '/content/ember/v2/**.md',
    output: '/content/ember-v2.json', 
  }, {
    src: '/content/ember/v1/**.md',
    output: '/content/ember-v1.json', 
  }, {
    src: '/content/ember-cli/v1/**.md',
    output: '/content/ember-cli-v1.json', 
  }]
})

ensure all deprecation content is up-to-date

Ember v1, see https://www.emberjs.com/deprecations/v1.x/
Ember v2, see https://www.emberjs.com/deprecations/v2.x/
Ember v3, see https://www.emberjs.com/deprecations/v3.x/
Ember-Data v2, see https://www.emberjs.com/deprecations/ember-data/v2.x/
Ember CLI v2, see https://www.emberjs.com/deprecations/ember-cli/v2.x/

Deployment broken

I'm just opening this issue so that we can keep track of the new deployment issues.

https://deprecations-app-prod.herokuapp.com/deprecations/ember/v1.x/#toc_ember-reducecomputedproperty-ember-arraycomputedproperty if you go to that link now it will break with an "Internal Server Error". I'm concerned because that seems to imply that it is running fastboot but we need to make sure that it is only using the prember generated static output.

Also, as per https://github.com/ef4/prember#configuring-your-webserver, we need to make sure we serve _empty.html on 404

Stop Prism executing more than once on a single page

Currently, Prism executes on {{deprecation-article}} render, but because we have multiple articles on a page, it will re-execute multiple times.

Simple enough to fix 😏

write some basic acceptance tests for the deprecation-app

We dont have test at the moment 🙀 We can do better :) Lets add some small acceptance tests that tests the basic functionality of the app

Use ember-collapsible-panel (see guides-app) for multi-level toc

App seems broken

try visiting http://emberjs.com/deprecations/v2.x#toc_injected-container-access. There are a bunch of script issues & the url is being redirected to production url instead of being proxied.

//cc @serenaf @mansona

Fix incorrect statements about the Ember CLI and deprecation warnings

It turns out that my past PR was wrong. Ember CLI version has no effect on the deprecation warnings shown.

Upgrade your ember-cli version to see which deprecations affect your app, when they are scheduled to change, and how to fix them.

This should say instead something like you can upgrade your app's minor version to see deprecations that will affect your app when a major version is released.

Create index file

Right now when running the deprecation app locally it appears empty as the only content we have is under http://localhost:4200/ember/v2.x.

We should copy the index file from the ember website/deprecations and link to the relevant routes in our app

Fix router url issue for proxy to work properly

Follow up with the Prember Static JSON issue

This is a placeholder issue to keep track of the forked dependencies in the package.json

I will not go into too much detail (check out the linked issues below) but the TLDR is that if you use the latest prember and the latest ember-cli this project will fail on the following command ember build -e production

Prember Issue: ef4/prember#12 Fix: ef4/prember#15
Ember-Cli PR: ember-cli/ember-cli#7615

Implement 404 page

Run a11y test over deprecation-app

See ember-learn/guides-app#46 as example and follow ;)

update html - first heading element should be an H1

Expected:
When the heading elements are used correctly, the styles are implemented appropriately.

There should be 1 h1 element per page- "Deprecations" is an h2 at the moment.
As a result, the other heading elements should be updated to ensure that the html is semantic. h1, then h2, then h3, etc., noting that there can be multiple sibling heading elements but no sibling heading elements should be skipped (i.e., h1 then h3) OR out of order (i.e. h2 then h4 then h3).

Fix code (single ``) styling

Since the id for this title is "locked" as legacy id: non-standard-ways-of-calling-code-ember-set-code-and-code-ember-get-code (aka including the backticks written out as code), we should preserve the backticks in the title. Relates to: #96.

(1) We should fix the styling of backtick code in the left hand side table of contents.

(2) We should fix the styling of backtick code in the title in-line.

Make sure each deprecation is wrapped in a `<section>` tag so that we can index the deprectaions app for search

I think the simplest thing to do is to change this <p> tag to be a <sectoin> tag https://github.com/ember-learn/deprecation-app/blob/master/app/templates/components/deprecation-article.hbs#L8

Once you do this you need to make sure that the styles are still ok 👍

update layout

The layout file for the emberjs website has changed, and this would need to use the same layout so the CSS will implement properly.

Mismatched IDs causing content to not be found

From @locks :

We have two problems.
Example: https://deprecations-app-prod.herokuapp.com/deprecations/v3.x/#toc_use-notifypropertychange-instead-of-propertywillchange-and-propertydidchange

The URL of the deprecation does not match what is present in the source code: emberjs/ember.js@dabdd89#diff-ad2e085482c0aad203f5f555a3497bcdR63
The id listed in the content does not match what is present in the source code: emberjs/ember.js@dabdd89#diff-ad2e085482c0aad203f5f555a3497bcdR61

What this means is that when someone clicks on the link from the deprecation warning, they will go to the top of the 3.x page. Further, if they try to do a “find in page” for the deprecation id present in the source code, they will not find a match.

Consider having a form on the app to submit a new deprecation

I would like to lower entry barriers to the various kinds of contributing as much as possible.
In that sense, I was wondering if having a web form that someone can use to submit a deprecation would be useful. I am unsure how we would deal with the whole GitHub auth bit…

Investigate random "extra" pages

https://emberjs.com/deprecations/instance-initializers/ linked to from https://emberjs.com/deprecations/v1.x/#toc_access-to-instances-in-initializers

Does it make sense that this sort of page is part of the deprecations app? maybe we could move it to the guides app, because it's more like a guide

Clarify use of private API for deprecation solution

defineProperty is private API, but we suggest it as a way to resolve a deprecation. We should give more guidance for alternatives:

Edward Faulkner’s comments from Slack:

it depends why they’re using it.

If they’re trying to use it as a polyfill for the native Object.defineProperty, they should just use that directly. Every browser Ember supports has that, and Ember itself depends on it.
If they’re trying to make computed properties on a plain old Javascript object, they should not do that. They should either make the object an Ember.Object and declare computed properties in the normal way, or they should keep the object as a POJO and use Object.defineProperty to make a native getter.
If they’re creating computed properties and can’t do it the normal way because they don’t know what the dependent keys are until after construction, they should do their own dependency observation with addObserver and notifyPropertyChange. This is an advanced thing to be doing, more likely in an addon that’s trying to present a whole new API on top of Ember than in an app.

Move `Ember.String` deprecation to v3

Someone—who totally isn't me,—delayed the Ember.String deprecation long enough that whenever it lands, it will be in the 3.x series.

We need to move the following two files from v2 to v3:

To do that you need to move the files from one folder to another, and then update the "until" to "4.0.0".

You don't need to worry about the content for now.

Add a postdeploy script to clear fastly cache on prod deployment

Convert over to using styleguide components

I'm just starting the list so if anyone else wants to add to it please feel free to edit this issue 👍

To-do

Accordion | Code | Component
Footer | Code | Component

[Discussion] Should we always show the anchorable-toc link

For:

knownasilya [2:22 PM]
hover only works for desktop, so having it always available is better

Against:

tbieniek [2:17 PM]
because it is often visually disturbing
seems like a common pattern to show it on hover

make sure deprecations-app is using same header and footer as guides-app

https://github.com/ember-learn/guides-app/pull/20/files

Port over deprecations

See new deprecations emberjs/website#2995 (comment)

Version Graphics Alignment

The Tomsters are looking a bit off to me on the index page. This is due to inconsistent dimensions in the images. I have a PR that tweaks the images individually through CSS but another option is to copy those images to this repo and scale them in Photoshop. Thoughts?

Current:

Proposal:

Add ability to pass attributes to broccoli-static-site-json so they come out in the JSON:API output

Currently the broccoli-static-site-json only supports attributes content (from the markdown) and title from the frontmatter.

The implementation is here: https://github.com/stonecircle/broccoli-static-site-json/blob/dc4b7680f75f9549dc62b9960d4bf5a575e5926f/index.js#L24

we would prefer to be able to pass attributes into the constructor:

new StaticSiteJson(`node_modules/@ember/guides-source/guides/`, {
  attributes: ['title', 'since', 'until']
})

Remove the use of ember-cli-cjs-transform

As per this comment, we shouldn't be including anything that isn't needed: #54 (comment)

We are using semver-compare in the Guides App without the need for ember-cli-cjs-transform so we can remove it here too 👍

Check whether specific sorting is needed for toc

@locks is there a specific ordering you want if a specific version has multiple deprecations?