Skip to content

As a WebWorks developer, I will be notified if my webworks.js file is not compatible with the framework. #104

kwallis opened this Issue May 24, 2012 · 9 comments

4 participants

Open Source Projects member
kwallis commented May 24, 2012

Acceptance Criteria

  • As soon as possible at runtime, validation of the compatibility of webworks.js and framework should take place.
  • If they are found to be incompatible, the user should be notified with the following text:
    • "The webworks.js javascript library (<insert "version" of webworks.js>) being used is incompatible with the WebWorks runtime. Please upgrade your webworks.js file to <insert compatible version>
Open Source Projects member

Proposed solution is to do a check at runtime that would ensure that
a) the version of the webworks.js in the client app (i.e. webworks- is the same as the version built with the framework
b) the contents are the same.

To validate the version we can simply check the filename of the apps active webworks.js (at runtime) and send this information via XHR to the Framework where it will compare against its webworks.js version.

I also suggest we make a change on the CI machine so that it provides some sort of unique id/version for branches that we can append to the webworks.js file. This can be something created by the branch name + build# (i.e. webworks-BB10-Packager-22.js). This is required if we want our internal devs to be able to take advantage of the webworks.js validation. Otherwise the webworks.js version for CI builds will never change, since the version normally comes from SCM builds ( etc).

To validate that the contents are the same, i propose we generate and store the md5 hash of webworks.js; Both at build time when the webworks.js is created and run time when the client applications webworks.js is loaded. The reason we would grab the hash at runtime is because the webworks.js file might be remote and package time is not sufficient. We would also need to write the build time Framework hash to a file that would be compared against at runtime. Checking hashes will help us determine if the actual file contents have changed.

The idea is that, when the applications webworks.js is loaded it will parse it's file name and hash itself and send this information via XHR to the Framework. The Framework would then compare this information to the hash and version generated at build time.

With this design the user is free to make changes to the webworks.js file and we won’t popup a warning. As long as the file name remains the same (i.e. webworks-, then we know it's the webworks.js we intended to run and It will be up to the user to ensure they don’t break anything.

@kwallis @nukulb Thoughts? Can we proceed with the proposed solution?

nukulb commented Jun 1, 2012

waiting on @jkeshavarzi who is working on answering-

How will a hash of webworks.js file be created at runtime? Read file or require but how?

Open Source Projects member

New proposal:

Update Frameworks build script [bundler.js] to;
1) Generate a hash of the built webworks.js
2) Create new property in webworks.js called window.webworks.version which would hold the hash
3) Also, write the hash to a file called webworks-version (to be compared against at runtime)

Update Packager build script [pack.js] to;
1) Include webworks-version in the bar.

At runtime, when the applications webworks.js is executed; It will send an XHR to the framework which contains it's window.webworks.version hash. The Framework will then compare this hash to the webworks-version file. If they do not match it will return an error and we will inform the user that their webworks.js is not compatible with the framework.

To sum things up;
window.webworks.version = Represents the hash for the running webworks.js
webworks-version - Represents the webworks.js hash for the particular Framework build you are using.

These two MUST match.
@kwallis @nukulb

nukulb commented Jun 1, 2012

@rcruz @jeffheifetz - thoughts? so far I really like it.


I like that the approach means the user can modify WebWorks.js. My only comment is that if at the end of the day we're comparing two strings, it doesn't really have to be a hash. It could just as easily be a simple version number.

Open Source Projects member
nukulb commented Jun 3, 2012

@jkeshavarzi - I think @jeffheifetz is saying that this will be just a random string (not a version number). If a developer modifies the webworks.js they can generate another "random string".
Basically @jeffheifetz - the proposed solution will automatically change the string being compared if the file is modified


@jkeshavarzi Is the assumption that we will be arbitrarily be increasing the version number of webworks.js? I do not believe we should increment the version number unless something has actually changed, otherwise we should throw an error anyway since its confusing behaviour.

@nukulb I do not believe this is the case. The proposed solution compares a pre-defined string and not one that is generated.

Open Source Projects member

A random string? That represents what? Is the idea to compare a random string generated for a particular webworks.js file? If it's just "random" then we are going to be complaining to the user and our devs each and every time their webworks app does not contain the exact webworks.js file that was built with the framework. They would have to update their webworks.js file each and everytime they built because a new "random" string was generated? This would be a disaster for CI builds because they would all have there own random string, whether the webworks.js changed or not.

The idea behind using a hash is it represents the actual file contents. i.e., we wont alert user unless the file has actually changed. If the file hasnt changed between builds then the hash will stay the same and no one has to update anything.

@jeffheifetz when you say version number are you referring to the version specified in the name (i.e. webworks-, or are you referring to the new proposed window.webworks.version?

@jeffheifetz The version number in the file name represents the scm build release version (i.e. This value only gets updated for SCM builds and is not reliable to compare against with ci builds.

@jeffheifetz The proposed solution does not compare a "pre-defined" string persay. It actually does compare a generated string; The hash, which is generated at build time.

If there is still confusion, perhaps we can setup a meeting on Monday.

@jkeshavarzi jkeshavarzi referenced this issue in blackberry-webworks/BB10-WebWorks-Framework Jun 7, 2012

Implemented webworks.js client/framework compatiblity mechanism [hash] #63

@nukulb nukulb closed this Jun 24, 2012
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Something went wrong with that request. Please try again.