Examples dramatically inflate the size of the project (100x the size of the source code)

[525c1e21-bd67-4735-ac99-b4b0e5262290]

As a user of terrible Australian internet I'm still at the mercy of large file sizes and at over 50MB three.js can take a while to download.

Of course given that nature of Git, it's irrelevant once the repo has been initially cloned. However I'm just raising the issue the people with internet access similar to mine may experience. This problem will only grow larger as more and more examples are contributed by the community.

Possible solutions

1. have the examples fetch large assets (textures, models) from a remote server (requires internet access)
2. utilise git submodules
3. establish a separate repo for the examples

My vote depends on how the examples will be targeted in the future. Do we wish for them to keep working against master forever?

I say they should be shipped with their own specific version of three.js and therefor seperated into their own repo. You should not have to fear breaking the API just to keep all of the examples working.

Of course to actually reduce the size of the git repo, the large objects will need to be purged from the internal git history (in some respects, "breaking" the repo) if one of these solutions is implemented. Alternatively, the git repo could be reinitialised from scratch but this seems rather harsh.

[mrdoob]

I think the examples must always work with the current code. They are, after all, the documentation. I think it's hard enough to keep up to date with all the changes in the API, having outdated examples would easily become a nightmare.

They are also very useful for testing new code.

Maybe having them on another repo could be an option. Need to research on this git submodules thing. Another option would be to optimise them :)

[525c1e21-bd67-4735-ac99-b4b0e5262290]

I agree that the examples should work against master. It's just not typically done this way and I didn't think you'd be prepared to do this; but nevertheless, excellent.

They should perhaps be a git submodule. It's basically as if they were in the main repo but they must be fetched separately with

git submodule init

or alternatively at clone time

git clone REPO --recursive

From the docs...

"After the clone is created, initialize all submodules within, using their default settings. This is equivalent to running git submodule update --init --recursive immediately after the clone is finished. This option is ignored if the cloned repository does not have a worktree/checkout (i.e. if any of --no-checkout/-n, --bare, or --mirror is given)"

[alteredq]

Having a working set of examples as integral part of master branch is IMHO critical feature (and one of the best features of Three.js).

They serve as documentation, test cases and give nice starting point for people to start experimenting with (having nice assets included is big plus).

I know, it's getting big :(, but I do think the benefits are well worth it and the size is still quite manageable.

Just for comparison, here are sizes of some other 3d libs/frameworks repos:

GLGE     59 MB
CubicVR 502 MB
x3d     613 MB
o3d   1,757 MB

At the beginning, I was also concerned whether to keep assets together with the rest, but now I'm quite persuaded it's a good thing.

Benefits of having everything together, able to simply clone a repository and get things running, are IMHO much worth increased waiting time while downloading. After all, clone/fetch are asynchronous operations. Slower simple automatic operation that can run in the background is preferable to sequence of more obscure manual operations.

[mrdoob]

O3D repo is 2GBytes? Wow.

[525c1e21-bd67-4735-ac99-b4b0e5262290]

Then it's settled. Closing...

[alteredq]

Yup, for example their beachdemo assets folder has 643 MB (includes Photoshop textures sources and 3ds max models).

Disk space and bandwidth is cheap. Fighting with problems caused by inconsistencies is very expensive and can be also extremely demoralizing.

[525c1e21-bd67-4735-ac99-b4b0e5262290]

Just out of curiosity approximately where do you guys live and what kind of connection do you have?

I'm in the far western suburbs of Brisbane, Australia and can only get what we call ADSL1 (~1.5MBPS). Although of late it's been nothing close to that speed...

[mrdoob]

Yeah, I have a pretty decent internet connection. However, I always have my demoscene reflex of creating optimising the size of things and I tend to be careful on filesizes.

pyrotechnick, I think you have a valid point, but before shifting priorities, stopping what we're working on and changing the whole repo, I guess it's fair to leave it until there is more than one person mentioning the issue.

Still, as alteredq mention, it's a one off download.

[alteredq]

Just out of curiosity approximately where do you guys live and what kind of connection do you have?

I have ok connection but nothing special around here (mine is the smallest option at 11 MB/s, the most expensive one here is currently 70 MB/s). Smallish town, central Europe.

[525c1e21-bd67-4735-ac99-b4b0e5262290]

OMFG! So jealous...

[fabricasapiens]

8 Mbps here in village in The Netherlands. With the available FTTH we can get to 30Mbps, but I have never seen any speed like 70Mbps... What connection is that?!