aframevr / aframevr/aframe

Outdated links & example code in documentation

Open
#5,207 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
JavaScript
Stars
17.6k
Forks
4.4k
PR merge metrics
No merged PRs in 30d

Description

Description:

  • A-Frame Version: 1.4.0
  • Platform / Device: all
  • Reproducible Code Snippet or URL: See below.

There are a range of very out-of-date links in the documentation, especially the getting started guide, that it would be great to fix.

Since upgrading to 1.4.0, aframe-teleport-controls has been broken. I was concerned about this as I knew it was referenced from the docs. Discussing with @vincentfretin we agreed that it would be a good idea to change the docs to refer to blink-controls, which is an actively maintained teleport component.

I started working on this here, but in the process of updating the docs, realized that there are a heap of similar issues that have stacked up.

Just considering the pages I've been editing, and a little bit of additional digging, the other issues are:

  1. Various outdated references to the A-Frame Registry. Easy to fix these to refer to the new Component Directory on the wiki, so I did that on the branch above.

  2. aincraft source code built in the example is also referred to as being in GitHub here in CodePen here, and in Glitch [here]( - all substantially out of date. Suggest we update the GitHub version to match the code in the tutorial, and retire the CodePen version.

Not sure about the Glitch version - I think it does add value over & above GitHub + GH Pages due to the remix option, so probably worth keeping. I assume there is already a set of Glitch demos that do get updated on a per-release basis, so shouldn't be too much overhead to add this to that list? (once we have an up-to-date working version on GitHub). I'm guessing only @dmarcos has access to the A-Frame Glitch account?

  1. The ECS tutorial page makes extensive use of the aframe-particle-system component, which has had a string of recent compatibility issues... @vincentfretin and I recently discussed bringing this into c-frame and under better maintenance. If we do that, we could update this page to refer to that version.

There's also a Glitch link here - again, probably worth keeping if we can, once we have updated working code.

  1. The Building a 360 image gallery probably needs a bunch of updates similar to the Minecraft Demo, needs Glitch updated etc.
    https://aframe.io/docs/master/guides/building-a-360-image-gallery.html
    Currently it runs at 1.0.4

  2. References to A-Frame Physics System here - easy to fix so I rolled these into the branch referenced above.

  3. Lots of references to A-Frame Extras. These should also refer to c-frame now (non-c-frame 6.1.1 is broken as of 1.4.1). I'll fix these up in the same way once we have a 6.2.0 release that is compatible with A-Frame 1.4.1.

Other things I spotted that could do with fixing up (and I'm sure there's more, I didn't do a comprehensive review of the docs)

  1. Outdated references to WebVR: move to WebXR.

  2. Outdated references to Newsletter & Blog. Remove?

  3. Outdated reference to supermedium browser. Remove?

Netting this down, there's a lot here altogether.... I probably didn't spot everything, but I think the scope above is feasible for me to take on fixing in fairly short order.

Proposed scope:

  • All links to recently adopted c-frame components updated.
  • The following demos working with 1.4.1 + compatible components, documented + working versions on GitHUb + Glitch:
  1. aincraft
  2. 360 gallery
  3. ECS example (aframe-registry example on Glitch)
  • Get aframe-particle-system adopted by C-Frame, and that version referenced by docs.
  • Other minor items mentioned above
  • Remove links to outdated code on codepen - glitch links are sufficient.

There's obviously a ton of other examples that are out of date, and there's another task to try to fix those up, but I think making it a priority to fix the examples explicitly used within the docs makes sense...

My dependencies on @dmarcos and @vincentfretin

  • Initial review of the above & buy-in to me making these changes. Are you happy with this all in one PR, or do you prefer to break it down?
  • Final review of updated docs/code
  • Once example code updated on GitHub, push updates to A-Frame glitch account.

One specific question where I'd appreciate input from @dmarcos: in several places the current docs explicitly name-checks certain community contributors, e.g. Don McCurdy for aframe-physics-system, aframe-extras, Fernando Serrano for aframe-teleport controls, IdeaSpace for aframe-particle-system.

Would you prefer to:

  1. continue to name-check the original contributors, even if they are no longer the maintainer
  2. name-check both original author & current maintainer
  3. just name-check the current maintainer
  4. or not include any names at all, and rely on GitHub repos to give credit where it's due?

I think I'd be inclined to go for 4, but very happy to take whatever approach is your preference.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the getting started guide and the linked teleport-controls-to-blink-controls branch, then inspect the named ECS tutorial, 360 image gallery, and HTML-and-primitives example. Check the current links and example versions before changing anything; done means the explicitly listed documentation links and demos point to maintained, working GitHub and Glitch versions.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
documentation, web-dev
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.