Policy for user-manual fIle downloads (re-evaluate) #56342

New Issue

Aaron Carlisle · 2018-08-13T04:09:48+02:00

Aaron Carlisle commented

2018-08-13 04:09:48 +02:00

We should re consider download files in the manual.

Should we have them?
Where should they be uploaded to?
- Old files were on wiki.blender.org. should we move these to the new wiki?
- Should these be in SVN then copied over during build?

Proposal:

I would like if we keep downloads and write some rules:

Must be CC-BY-SA 4.0 Int
Must be under 10mb for a zip
Files should be properly named with the blender version they were last updated for
Files are stored in the svn repo
A page should try limit itself to 1 example
blend-file should include a txt-file (opened in blender text editor) that describes the example and steps on how to use it.
All files should be stored as a zip
No py-files or other executable code (security reasons)

We should re consider download files in the manual. - Should we have them? - Where should they be uploaded to? - Old files were on wiki.blender.org. should we move these to the new wiki? - Should these be in SVN then copied over during build? ## Proposal: I would like if we keep downloads and write some rules: Must be CC-BY-SA 4.0 Int Must be under 10mb for a zip Files should be properly named with the blender version they were last updated for Files are stored in the svn repo A page should try limit itself to 1 example blend-file should include a txt-file (opened in blender text editor) that describes the example and steps on how to use it. All files should be stored as a zip No py-files or other executable code (security reasons)

Aaron Carlisle commented

2018-08-13 04:09:48 +02:00

Added subscribers: @Blendify, @ideasman42

blender-admin commented

2018-08-13 04:09:48 +02:00

#86545 was marked as duplicate of this issue

blender-admin commented

2018-08-13 04:09:48 +02:00

blender/blender#82008 was marked as duplicate of this issue

blender-admin commented

2018-08-13 04:09:48 +02:00

#77534 was marked as duplicate of this issue

blender-admin commented

2018-08-13 04:09:48 +02:00

#58203 was marked as duplicate of this issue

Yevgeny Makarov commented

2018-08-13 08:08:04 +02:00

Added subscriber: @jenkm

Yevgeny Makarov commented

2018-08-13 08:08:04 +02:00

Some remarks:

There are very useful examples files, such as for the Data Transfer Modifier.

Some examples are very simple and/or duplicated by screenshot or video, and can be removed.

And also there are old blend-files that don't work in new Blender versions, for example in the Physics section. There should be an opportunity to update them, if they remain in the manual.

*Some remarks:* There are very useful examples files, such as for the Data Transfer Modifier. Some examples are very simple and/or duplicated by screenshot or video, and can be removed. And also there are old blend-files that don't work in new Blender versions, for example in the Physics section. There should be an opportunity to update them, if they remain in the manual.

Aaron Carlisle commented

2018-08-14 22:07:22 +02:00

I would like if we keep downloads and write some rules:

Must be CC-BY-SA 4.0 Int
Must be under 10mb for a zip
Files should be properly named with the blender version they were last updated for
Files are stored in the svn repo
A page should try limit itself to 1 example
blend-file should include a txt-file (opened in blender text editor) that describes the example and steps on how to use it.
All files should be stored as a zip
No py-files or other executable code (security reasons)

Anyone have any thoughts or concerns here?

I would like if we keep downloads and write some rules: - Must be CC-BY-SA 4.0 Int - Must be under 10mb for a zip - Files should be properly named with the blender version they were last updated for - Files are stored in the svn repo - A page should try limit itself to 1 example - blend-file should include a txt-file (opened in blender text editor) that describes the example and steps on how to use it. - All files should be stored as a zip - No py-files or other executable code (security reasons) Anyone have any thoughts or concerns here?

Aaron Carlisle commented

2018-11-30 14:51:46 +01:00

Added subscriber: @brita

Inês Almeida commented

2018-11-30 18:26:03 +01:00

Hi Aaron, I couldn't find this task when I searched for an existing one.

Replying to your questions:

I propose to put media files in the SVN repo for the manual under a new folder files/ in the root directory. Not in the new developer wiki.

```
Must be CC-BY-SA 4.0 Int
```

The files on the archived wiki were uploaded under the Open Content License or the Blender Artistic License.
The Blender Manual switched from OCL to CC-BY-SA 4.0.
I also wonder if the files should be re-uploaded with this license or keep one of the above?

```
Must be under 10mb for a zip.
```

I think we can recommend a maximum size, but I wouldn't strictly enforce it. 10MB seems low for media.

Files should be properly named with the blender version they were last updated for

Renaming would break links, I would not put the Blender version on the file name.
We could ask for .blend files to have a text buffer with the version, besides the license, but this would also mean bumping all binary files on every blender release.
Since the manual is now versioned, I think there is no need to manually add versions to the files. They still should be checked periodically, but that can be part of the release process checklist.

```
Files are stored in the svn repo
```

Yes.

A page should try limit itself to 1 example

I don't see the reason for this limitation.

blend-file should include a txt-file (opened in blender text editor) that describes the example and steps on how to use it.

A blend file (or a zip), should always have a text with the license and readme. However, I'd keep text to a minimum and refer to the manual page.

```
All files should be stored as a zip
```

I also don't see a reason for this limitation.

No py-files or other executable code (security reasons)

Python code may be needed as a demo, although most python examples are already shipped with Blender.
I wouldn't limit this either.

Hi Aaron, I couldn't find this task when I searched for an existing one. Replying to your questions: I propose to put media files in the SVN repo for the manual under a new folder `files/` in the root directory. **Not** in the new developer wiki. > - Must be CC-BY-SA 4.0 Int The files on the archived wiki were uploaded under the Open Content License or the Blender Artistic License. The Blender Manual switched from OCL to CC-BY-SA 4.0. I also wonder if the files should be re-uploaded with this license or keep one of the above? > - Must be under 10mb for a zip. I think we can recommend a maximum size, but I wouldn't strictly enforce it. 10MB seems low for media. > - Files should be properly named with the blender version they were last updated for Renaming would break links, I would not put the Blender version on the file name. We could ask for .blend files to have a text buffer with the version, besides the license, but this would also mean bumping all binary files on every blender release. Since the manual is now versioned, I think there is no need to manually add versions to the files. They still should be checked periodically, but that can be part of the release process checklist. > - Files are stored in the svn repo Yes. > - A page should try limit itself to 1 example I don't see the reason for this limitation. > - blend-file should include a txt-file (opened in blender text editor) that describes the example and steps on how to use it. A blend file (or a zip), should always have a text with the license and readme. However, I'd keep text to a minimum and refer to the manual page. > - All files should be stored as a zip I also don't see a reason for this limitation. > - No py-files or other executable code (security reasons) Python code may be needed as a demo, although most python examples are already shipped with Blender. I wouldn't limit this either.

Inês Almeida commented

2018-12-15 16:55:16 +01:00

Added subscriber: @Sergey

Inês Almeida commented

2018-12-15 16:55:16 +01:00

It's been some time without a reply.
@Sergey @ideasman42 do you have anything against putting media files in the manual SVN under a new files/ folder in the root directory?

These are the only rules I would include:
Guidelines for Media Files

Files should be accompanied by a text stating its license and purpose. This text can be in a text buffer for a .blend file, or in a .txt inside a zip accompanying other files.
The license should be CC-BY-SA 4.0 or the original license for a pre-existing file. Do not submit content under an incompatible license or someone else's work without their permission.

This file is a part of the Blender Manual (https://docs.blender.org/manual) by the Blender Documentation Team
and it is licensed under CC-BY-SA v4.0 (https://creativecommons.org/licenses/by-sa/4.0).

Don't include information that is easily outdated. eg. Blender versions, dates and expressions such as "since last week" or "the new option". Versioning and history information can be extracted from SVN.
Name the file carefully and do not include a Blender version in the naming.
Check the size of the file before uploading, and if possible, minimize it.

It's been some time without a reply. @Sergey @ideasman42 do you have anything against putting media files in the manual SVN under a new `files/` folder in the root directory? These are the only rules I would include: **Guidelines for Media Files** - Files should be accompanied by a text stating its license and purpose. This text can be in a text buffer for a .blend file, or in a .txt inside a zip accompanying other files. The license should be `CC-BY-SA 4.0` or the original license for a pre-existing file. Do not submit content under an incompatible license or someone else's work without their permission. ``` This file is a part of the Blender Manual (https://docs.blender.org/manual) by the Blender Documentation Team and it is licensed under CC-BY-SA v4.0 (https://creativecommons.org/licenses/by-sa/4.0). ``` - Don't include information that is easily outdated. eg. Blender versions, dates and expressions such as "since last week" or "the new option". Versioning and history information can be extracted from SVN. - Name the file carefully and do not include a Blender version in the naming. - Check the size of the file before uploading, and if possible, minimize it.

Sergey Sharybin commented

2018-12-15 17:33:26 +01:00

@brita, i am all for keeping things locally in terms where they belong to. Makes it easier to version, control consistency, and see where they actually are supposed to be put.

Not sure about such a strict rule about the license. Can one submit a public-domain things (images and diagrams describing/showing some algorithm)? How is that aligned with content of open movies and the blender cloud?

@brita, i am all for keeping things locally in terms where they belong to. Makes it easier to version, control consistency, and see where they actually are supposed to be put. Not sure about such a strict rule about the license. Can one submit a public-domain things (images and diagrams describing/showing some algorithm)? How is that aligned with content of open movies and the blender cloud?

Inês Almeida commented

2018-12-15 17:55:40 +01:00

@Sergey why do you think the licensing rule is strict?
A public domain diagram of an algorithm can be uploaded with its original license and author if needed. I think public domain, other versions of CC and the licenses used in the previous Blender wiki are all perfectly fine.
The Blender Cloud says: "Unless notified otherwise, all digital content (webpages, video, artwork, 3D data) is available under the Creative Commons Attribution 4.0.". Blender Cloud textures are CC0. So these can also be uploaded with their original license.

The only thing you can't do is upload some proprietary thing which is then redistributed when its license doesn't allow it. Also re-licensing someone's work without their consent would be bad.

@Sergey why do you think the licensing rule is strict? A public domain diagram of an algorithm can be uploaded with its original license and author if needed. I think public domain, other versions of CC and the licenses used in the previous Blender wiki are all perfectly fine. The Blender Cloud says: "Unless notified otherwise, all digital content (webpages, video, artwork, 3D data) is available under the Creative Commons Attribution 4.0.". Blender Cloud textures are CC0. So these can also be uploaded with their original license. The only thing you can't do is upload some proprietary thing which is then redistributed when its license doesn't allow it. Also re-licensing someone's work without their consent would be bad.

Yevgeny Makarov commented

2019-02-13 09:52:37 +01:00

It seems easier not to use the .blend files in the manual at all. Тoo many problems.

not one of the current files will not work/look well in 2.8
license (contributor may upload something is not suitable)
security (py-files or other executable code)
and so on
There may be links to external files in the see more section, for example files from developers in release logs.

It seems easier not to use the .blend files in the manual at all. Тoo many problems. - not one of the current files will not work/look well in 2.8 - license (contributor may upload something is not suitable) - security (py-files or other executable code) - and so on There may be links to external files in the see more section, for example files from developers in release logs.

Campbell Barton changed title from ~~FIle downloads: re-evaluate~~ to Policy for user-manual fIle downloads (re-evaluate)

2019-12-23 23:27:38 +01:00

Aaron Carlisle commented

2020-06-06 22:07:14 +02:00

Added subscriber: @NoahElRhandour

Germano Cavalcante commented

2020-10-23 22:10:20 +02:00

Added subscribers: @skarkkai, @mano-wii

Aaron Carlisle commented

2021-03-14 00:18:43 +01:00

Added subscribers: @fsdoma, @frank

Aaron Carlisle commented

2021-03-14 00:21:51 +01:00

An update on this, I want to leverage the Blender cloud for hosting demo files, similar to what we do for the files on https://www.blender.org/download/demo-files/

I still need to discuss this with members of the cloud, I want to also work on a written policy for user-submitted demo files.

An update on this, I want to leverage the Blender cloud for hosting demo files, similar to what we do for the files on https://www.blender.org/download/demo-files/ I still need to discuss this with members of the cloud, I want to also work on a written policy for user-submitted demo files.

Frank commented

2021-03-15 14:55:15 +01:00

Hello,

I came here from another thread (which I opened and it shows to be a Duplicate).

First my motivation:

I am a Blender USER and try to learn it
The Manual is often very unclear for someone who has no clue (yet)
"Tutorials" on YouTube about a topic are almost always splattered with tons of unrelated things
I made some experimenting .blend files for myself and think I could share them
(as has shown for myself) Giving a new user examples to play with makes getting the grasp easier

I found some time to study the whole thread:

License - agree
Blender version in file name - disagree for naming conventions reason

(The explanatory text inside the .blend file should contain this. The user using the file has to know this)

Size limit - disagree: This heavyly depends on the manual topic the file covers
SVN repository - can if they belong to the manual

(My idea is to exactly copy the structure of the manual itself. There could be links from headings in the 
 manual to the .blend file covering the topic. A user would have something to experiment with while studying
 the manual.)

Blender Cloud - good idea but an easy to follow way to find (for instance) Blender -> Physics -> Cloth

in the cloud has to be available.

Some thoughts how such examples could be provided:

If on the cloud or on some central Blender v. x.y Examples URL it should be mentioned that the examples are

FOCUSED. 
For instance my Cloth and Softbody examples contain an animation to demonstrate collision and deformation.
I instruct the user to place an object and press Ctrl-I, move the object and press Ctrl-I again with a comment
that what she does with this is explained in the animation example file (... and manual section ;)).

BE focused! For instance my material example contains 2 scenes - one for surface and one for volumes leaving

lighting, viewport and camera settings i.e. completely out

Refer to the manual. The examples are provided with some startup values to experiment with. This teaches the

user how to work with the manual and the experimenting approach helps to understand the manual better

Highlight cross dependencies. For instance material transparency works only if Render -> Scene Space Reflections ->

Refraction is set to On. In the manual such things are not mentioned at all.

Be concrete. In the example above: Instead of "Turn on Refraction" say: "In Render -> Scene Space Reflections check

Refraction". Blender is a very complex piece of software. To find the single settings can be hard for a new user.

Avoid shortcuts and searches. Instead of Ctrl+H or even worse F3 -> Hook say Menu Vertex -> Hooks. The user is

able to follow what he is doing AND learns the shortcuts (they are mentioned in the menu items).

Use simple Blender standard meshes. For learning how to move an object from A to B it is disturbing to model a

fancy car.

Maybe a statement like: "This file is meant to be a companion to . Feel free to use this

manual section to experiment with the settings here." could be included in the Explanations text in the file.

01_RigidBody.blend

Do we have some URL to where I can upload what I have (so far)?

In regard to the link from Aaron - waaaay to fancy :D
I upload an example (the things discussed here not included yet)

Just my 2 cent.

Hello, I came here from another thread (which I opened and it shows to be a Duplicate). First my motivation: - I am a Blender USER and try to learn it - The Manual is often very unclear for someone who has no clue (yet) - "Tutorials" on YouTube about a topic are almost always splattered with tons of unrelated things - I made some experimenting .blend files for myself and think I could share them - (as has shown for myself) Giving a new user examples to play with makes getting the grasp easier I found some time to study the whole thread: - License - agree - Blender version in file name - disagree for naming conventions reason ``` (The explanatory text inside the .blend file should contain this. The user using the file has to know this) ``` - Size limit - disagree: This heavyly depends on the manual topic the file covers - SVN repository - can if they belong to the manual ``` (My idea is to exactly copy the structure of the manual itself. There could be links from headings in the manual to the .blend file covering the topic. A user would have something to experiment with while studying the manual.) ``` - Blender Cloud - good idea but an easy to follow way to find (for instance) Blender -> Physics -> Cloth ``` in the cloud has to be available. ``` Some thoughts how such examples could be provided: - If on the cloud or on some central Blender v. x.y Examples URL it should be mentioned that the examples are ``` FOCUSED. For instance my Cloth and Softbody examples contain an animation to demonstrate collision and deformation. I instruct the user to place an object and press Ctrl-I, move the object and press Ctrl-I again with a comment that what she does with this is explained in the animation example file (... and manual section ;)). ``` - BE focused! For instance my material example contains 2 scenes - one for surface and one for volumes leaving ``` lighting, viewport and camera settings i.e. completely out ``` - Refer to the manual. The examples are provided with some startup values to experiment with. This teaches the ``` user how to work with the manual and the experimenting approach helps to understand the manual better ``` - Highlight cross dependencies. For instance material transparency works only if Render -> Scene Space Reflections -> ``` Refraction is set to On. In the manual such things are not mentioned at all. ``` - Be concrete. In the example above: Instead of "Turn on Refraction" say: "In Render -> Scene Space Reflections check ``` Refraction". Blender is a very complex piece of software. To find the single settings can be hard for a new user. ``` - Avoid shortcuts and searches. Instead of Ctrl+H or even worse F3 -> Hook say Menu Vertex -> Hooks. The user is ``` able to follow what he is doing AND learns the shortcuts (they are mentioned in the menu items). ``` - Use simple Blender standard meshes. For learning how to move an object from A to B it is disturbing to model a ``` fancy car. ``` - Maybe a statement like: "This file is meant to be a companion to <Blender Manual Section>. Feel free to use this ``` manual section to experiment with the settings here." could be included in the Explanations text in the file. ``` [01_RigidBody.blend](https://archive.blender.org/developer/F9892685/01_RigidBody.blend) Do we have some URL to where I can upload what I have (so far)? In regard to the link from Aaron - waaaay to fancy :D I upload an example (the things discussed here not included yet) Just my 2 cent.

Aaron Carlisle commented

2021-03-23 04:12:23 +01:00

Size limit - disagree: This heavyly depends on the manual topic the file covers

This was mostly focused on my original idea of using svn but now, we want to host on the cloud or download.blender.org
With these, I care less about the size limit, although files should not be too large to create server download bottlenecks (about 200mb)

Highlight cross dependencies. For instance material transparency works only if Render -> Scene Space Reflections -> Refraction is set to On. In the manual such things are not mentioned at all.

Such dependencies in the manual should be given, if not that is a case the documentation needs an update.

Be concrete. In the example above: Instead of "Turn on Refraction" say: "In Render -> Scene Space Reflections check Refraction". Blender is a very complex piece of software. To find the single settings can be hard for a new user.

Explanations should be part of the manual and I want to avoid pointing to the location of properties or operators and instead link to its documentation and provide a reference box there with the menu location and shortcut.
This avoids text becoming out of date and making things easier to maintain.

Do we have some URL to where I can upload what I have (so far)?

Not currently, we want to iron out the details of this task first.

> Size limit - disagree: This heavyly depends on the manual topic the file covers This was mostly focused on my original idea of using svn but now, we want to host on the cloud or download.blender.org With these, I care less about the size limit, although files should not be too large to create server download bottlenecks (about 200mb) > Highlight cross dependencies. For instance material transparency works only if Render -> Scene Space Reflections -> Refraction is set to On. In the manual such things are not mentioned at all. Such dependencies in the manual should be given, if not that is a case the documentation needs an update. > Be concrete. In the example above: Instead of "Turn on Refraction" say: "In Render -> Scene Space Reflections check Refraction". Blender is a very complex piece of software. To find the single settings can be hard for a new user. Explanations should be part of the manual and I want to avoid pointing to the location of properties or operators and instead link to its documentation and provide a reference box there with the menu location and shortcut. This avoids text becoming out of date and making things easier to maintain. > Do we have some URL to where I can upload what I have (so far)? Not currently, we want to iron out the details of this task first.

Sign in to join this conversation.

No Label

Download

What's New

Blender Studio

Manual

Developers Blog

Documentation

Benchmark

Blender Conference

Development Fund

One-time Donations

Policy for user-manual fIle downloads (re-evaluate) #56342

Proposal: