-
Notifications
You must be signed in to change notification settings - Fork 40
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
New JSON structure #5
Comments
We could even add a |
You could also add a |
If we are going to add property |
@dmarcos 👍 for |
You have schema information scattered in multiple places. What happens if you modify / remove component properties? You have to also modify the |
I agree that having this |
The grouping seems to be purely presentational and should be kept out of the core. Else we couple A-Frame to the Inspector when the Inspector should have been a clean abstraction layer on top of A-Frame. IMO, we should just leave out grouping and stay with simple alphabetical order. Alphebetical order ensures consistency between presentation of all components. Grouping adds maintenance and potential for version mismatches against this field. |
I agree that we should try not to include any inspector specific feature in the core that's why I proposed to do it here. Regarding using or not grouping, we'll leave it as optional, but I believe it's quite useful even if it need some maintenance, just take a look at the drafts that @feiss did here aframevr/aframe-inspector#303. |
I think we can simplify by not having the JSON be aware of different A-Frame versions. The JSON itself could be tagged/versioned. That way you don't have to worry about maintaining multiple metadata for different A-Frame versions of a component in the same file.
|
And what about the case when we just release the new aframe version let's say |
We can perhaps have a build step to concatenate all the tags to get: {
"0.3.0": {
},
"0.4.0": {
}
} This provides some information on the minimum version a component was known to support. We could provide a compat warning on 0.4.0 if a version supported 0.3.0 but nothing was explicitly updated for 0.4.0. Any components that require an update to work can register themselves with the new version of the JSON. This might mean that every upgrade, we have a fresh working JSON for current version, and a built JSON consisting of all older versions. |
Unrelated: we could also have build steps to pre-populate fields from NPM (or package.json found on GitHub). |
I believe the system we are creating mirrors Firefox add-ons:
Here is how they handle compatibility: https://developer.mozilla.org/en-US/docs/Extension_Versioning,_Update_and_Compatibility |
Most of the URLs here include either a version number or a SHA1 – that's confusing to me for two reasons:
I recognize that NPM itself doesn't do everything we need, but I wonder if component versioning and registration could build on its APIs? The JSON here could theoretically be stripped down as far as: [
'aframe-collider',
'aframe-explode',
'aframe-spawner'
] And then use something like npms-api to pull package metadata ~daily and pick up the most recent version, its URL, and popularity data: https://api.npms.io/module/aframe-leap-hands. Or grab the From package.json alone, a lot can be determined. A-Frame version compatibility should be a // package.json
{
"name": "aframe-leap-hands",
"author": "Don McCurdy <dm@donmccurdy.com>",
"version": "0.5.1",
"description": "Leap Motion component for A-Frame VR", // generic description
"peerDependencies": {
"aframe": "^0.3.1"
},
"aframe": [{
"type": component | system | primitive,
"name": "leap-hands",
"description": "Displays a skeletal hand using Leap Motion", // aframe-specific description
"dist": "dist/bundle.min.js",
"rating": comfortable | moderate | intense | non-vr,
"tags": ["input", "physics"]
}]
} Some new
|
I'm not an expert on npm and its api but as far I can understand It seems to be a nice idea what @donmccurdy proposes. |
You could publish your component to NPM, and use a service like unpkg.io (formerly npmcdn). This allows you to get a URL like |
I do like reusing package.json though. |
But if you use the URL +1 for reusing package.json |
The URL will access the latest version up until the latest major version. So I think the policy should be similar to Firefox add-ons. When upgrading to the next A-Frame version, attempt to make all the previous ones work, with a large disclaimer. If a new ("major") version is uploaded, then it will override the previous one. So you sort of have a cascading effect. |
Ok, I was thinking in the case where the component's versions are not related to aframe's versions, let's say that the |
The URL is mostly for developer convenience so they can push patches without having to PR. Not related to how we version. I think the Firefox add-on model still applies, it can work even if the numbers don't match. We just have to know the last minimum working version. |
Ok. So the workflow will be something like this?:
And from the inspector's side:
|
I don't think we should tie the version number of the component to A-Frame. We should keep track of that somewhere else. How about separate JSON for each version of A-Frame?
Then we have a build step to process the JSONs with the following policy. Each new version of A-Frame assumes all of the same components from the previous version, but a disclaimer will be raised if there isn't an update component explicitly mentioned. Using the example above:
And perhaps an extra field to list components that we know do not work from the previous version.
|
The last part ("an extra field to list components that we know do not work from the previous version") sounds premature, I think. Maybe there is some way of codifying that, without requiring a description of the component at all historical revisions be maintained on the repo's HEAD? // package.json
{
// ...
"aframe": {
"type": component | system | primitive,
"name": "leap-hands",
"description": "Displays a skeletal hand using Leap Motion",
"dist": "dist/bundle.min.js",
"history": { // a-frame version → component version
"^0.2.0": "^1.5.0",
"^0.3.0": "^1.6.0",
"^0.4.0": "stable",
}
}
} The build process would fetch |
A problem I see is having to chase down authors to update their I was thinking we'd usually only actively maintain the latest version's JSON, and maybe a tiny bit of the previous version. The rest live at the Whatever we do, I like that policy that we should assume that components work on the next version. If they don't have an explicitly listed new version, we throw a warning. And if we somehow know a component doesn't work, then we have a way to exclude it until a new version is uploaded. |
In any case we should have some kind of caching for the component's info right? I mean instead of reading the array of npm-components-names and start fetching their package.json to generate the list of available components with a some info in the inspector. |
You mean we cache fetched component metadata in the repo? Then yeah, we'd do that in the build steps. |
Yep exactly |
If you cache the component metadata from npm you need to automate the process to do it periodically to make sure that the info is up to date. |
To include components in the curated list... Is there a cheap way to do a community based curation a la hacker news? People upvote components published in NPM and there's a pre stablished criteria to include them in the "official" list. We would keep the criteria "secret" and "dynamic" to prevent people gaming the system. |
That could be an "v2" design for the current "do a PR with your new component and we'll review it". In any case we will end up having a list of components and the rest of the process will be as discussed before. So we could create a new issue with your proposal to mark it as "enhancement" and leave it for a new iteration when we already know that this is working and we have a huge amount of components |
There is an open, unofficial API for NPM popularity data. Could manually review that, as you said, although NPM seems comfortable reporting "Packages people 'npm install' a lot" on their homepage, so maybe they validate things themselves. |
Cool, didn't know that!. What I mean about leaving it for "v2" is to try to get something easy to try as a POC for some packages and a manually review them so we could have something working already as a MVP and then iterate from there, instead of going directly for a "overengineering" solution right at the beginning. |
Popularity could help us curate them, but I don't think the system should be based on popularity. One of the whole points of component discovery is to make well-built components more popular in the first place. We'd be missing out on lesser-known components that may be well-built. |
Following with our vidyo about the MVP:
That data could be stored within the We could get rid of that and add a validation of that metadata by including it directly here. At the end that metadata is just specific from our curated list, it's not needed or affect anyhow the component outside from this use. For the MVP we could have the whole list on one JSON, similar to:
But later we could have a separated file for each component if the size increased a lot. The version control will be handled as @ngokevin proposed by having a file for each version and we'll keep updating that file on each new aframe's release. We'll use the component's json to show the data in the inspector without need to do any extra fetch or cache anything, and once we decide to include a component, we'll use the npm API to fetch the correct version of the file to inject. What do you think? |
it's going to be a correspondence between the json and the package of the version used? |
That will be handled on the versions' files:
|
do you want a file per version or just tagging the repo with the aframe versions? |
Umm I'm not sure, because once you tag the repo you can't modify it right? And sometimes you maybe keep increasing the aframe versions and the users fix compatibility issues with older versions at any time. How can we handle that? And what about the current version that it's still not tagged? |
Here's my start: #7 Yeah, for now, I think it's easiest for maintenance to keep a file per major version, and simplest for the build script if everything is not scattered across branches/tags. |
I like it! :) But don't you think we should need a components.json with every component that we've in our repo? Otherwise we should go through all the versions files to collect the components that maybe are not yet tested for the current version. Also we could get rid of the duplications of |
Hm, yeah, that makes sense to be able to see a single component's support throughout the versions in one place. Something like. // registry.json
{
"components": {
"aframe-bmfont-text-component": {
"name": "bmfont-text",
"aframeVersion": {
"0.3.0": {
version: "0.1.x",
path: "dist/aframe-bmfont-text-component.min.js"
},
"4.0.0": {
version: null // Means we found it does NOT work. Needs an update.
}
}
}
}
} |
There's the npm name and the component name. We need the npm name to figure out where to fetch metadata. We need the component name for like...displaying in the Inspector dropdown, and this information isn't available through npm yet (unless we try to parse the JS file). |
Yep, I agree with the component/npm name, I was wondering how to prevent the duplication across the versions files. |
I was thinking if we don't list the version, we show the warning (it may or may not work). If you do list the version, and set |
Yep, good point 👍 |
That will helps also to review the remaining components |
Is the component version, "0.1.x", using a wildcard? If so, is there a programmatic way to get the latest version matching that wildcard from GitHub/NPM without just making fetch requests in a for-loop? |
Yeah, unpkg.com (formerly npmcdn) will give you the latest version if you use a fuzzy version. https://unpkg.com/aframe-bmfont-text-component@*/dist/aframe-bmfont-text-component.min.js |
the initial json builder completed at #7 We can file more issues to refine the policy or tweak the structure. |
yeah! It was a nice discussion 👍 |
🎉 |
Following the discussion we had (@dmarcos, @ngokevin) about it last week...
The current structure is:
Add some new parameters:
version
andurl
:{"0.3.0": "http://blabla", "0.4.0": "http://blabla4"}
mergeTo
or similar.With the changes proposed the JSON could looks like the following:
The text was updated successfully, but these errors were encountered: