studio/blender-studio-tools
13
30
Fork 19
Code Issues 20 Pull Requests 3 Projects Releases 1 Activity

Documentation: Flamenco Setup is misleading #284

New Issue
Closed
opened 2024-04-16 15:30:31 +02:00 by Sybren A. Stüvel · 8 comments
Sybren A. Stüvel commented 2024-04-16 15:30:31 +02:00
Owner
Copy Link

The Flamenco documentation is misleading, in a few ways:

  • It promotes the creation of a local directory, and configuring it to serve as shared storage. This isn't going to work without NFS/Samba setup.
  • It tells the user to use a relative path for the shared storage, which should simply never be done. It's not tested with Flamenco, and can cause unexpected failures.
  • Same for the path to Blender, which again is untested and can cause problems.

I would expect other information here, like how the Flamenco add-on is not really like the others, and should be farm-version-dependent, rather than per-project.

The [Flamenco documentation](https://studio.blender.org/pipeline/td-guide/addon_setup#flamenco-setup) is misleading, in a few ways: - It promotes the creation of a local directory, and configuring it to serve as shared storage. This isn't going to work without NFS/Samba setup. - It tells the user to use a relative path for the shared storage, which should simply never be done. It's not tested with Flamenco, and can cause unexpected failures. - Same for the path to Blender, which again is untested and can cause problems. I would expect other information here, like how the Flamenco add-on is not really like the others, and should be farm-version-dependent, rather than per-project.
👍 1
Nick Alberelli added the
Kind
Documentation
Priority
High
 labels 2024-05-07 21:30:11 +02:00
Nick Alberelli changed title from Flamenco documentation is misleading to Documentation: Flamenco Setup is misleading 2024-05-08 16:15:56 +02:00
Nick Alberelli commented 2024-05-08 18:17:22 +02:00
Member
Copy Link

Thanks for reporting I have resolved this issue now in a recent commit. For consistency sake, we will rely soley on the Flamenco Quickstart guide to walk users through the process of setting up the farm and this page will now just provided additional information/guidance for Blender Studio Users (like pointing out their blender path may be stored at a relative directory.)

see: https://studio.blender.org/pipeline/td-guide/flamenco_setup

Thanks for reporting I have resolved this issue now in a recent commit. For consistency sake, we will rely soley on the Flamenco Quickstart guide to walk users through the process of setting up the farm and this page will now just provided additional information/guidance for Blender Studio Users (like pointing out their blender path may be stored at a relative directory.) see: https://studio.blender.org/pipeline/td-guide/flamenco_setup
Sybren A. Stüvel commented 2024-05-10 11:24:17 +02:00
Author
Owner
Copy Link

Thanks, much better.

In the current docs:

To learn more about how files are stored on the farm, see the Shaman Storage System documentation.

Here the link points to https://flamenco.blender.org/usage/shared-storage/shaman/#how-does-it-work, which effectively makes the reader skip the table of contents and the introduction. It would be better to just link to the page itself, and not any specific header.

If you are storing your Blender executable at a relative path, consider creating a symlink to an absolute directory on each workstation, or storing a copy of Blender at an absolute directory (the same on each machine).

A storage location is never absolute or relative. It's the reference to that location that can be absolute / relative. I personally wouldn't know what "If you are storing your Blender executable at a relative path would mean. Probably because I'm not familiar with the rest of the TD guide ;-)

Place a copy of the Add-On zip in the your_project_name/shared/artifacts/addons/ directory.

AFAIK this is not how the Blender Studio artist machines are set up. I would also strongly recommend against placing the Flamenco add-on in the project-specific directory, for the same reason that's written below that sentence (the version being farm dependent).

I think it would be better to first describe the approach we use at the studio (not sure which approach that is exactly, but I suspect it's going via the Gentoo build server), as that works pretty well for us in practice. And then as a special case describe the per-project approach, where the description and the warning are in the same block of text so that they're visually closely related.

Thanks, much better. In the current docs: > To learn more about how files are stored on the farm, see the [Shaman Storage System](https://flamenco.blender.org/usage/shared-storage/shaman/#how-does-it-work) documentation. Here the link points to https://flamenco.blender.org/usage/shared-storage/shaman/#how-does-it-work, which effectively makes the reader skip the table of contents and the introduction. It would be better to just link to the page itself, and not any specific header. > If you are storing your Blender executable at a relative path, consider creating a symlink to an absolute directory on each workstation, or storing a copy of Blender at an absolute directory (the same on each machine). A storage location is never absolute or relative. It's the reference to that location that can be absolute / relative. I personally wouldn't know what "If you are storing your Blender executable at a relative path would mean. Probably because I'm not familiar with the rest of the TD guide ;-) > Place a copy of the Add-On zip in the `your_project_name/shared/artifacts/addons/` directory. AFAIK this is not how the Blender Studio artist machines are set up. I would also strongly recommend against placing the Flamenco add-on in the project-specific directory, for the same reason that's written below that sentence (the version being farm dependent). I think it would be better to first describe the approach we use at the studio (not sure which approach that is exactly, but I suspect it's going via the Gentoo build server), as that works pretty well for us in practice. And then as a special case describe the per-project approach, where the description and the warning are in the same block of text so that they're visually closely related.
Sybren A. Stüvel added
Priority
Medium
 and removed
Priority
High
 labels 2024-05-10 11:26:19 +02:00
Nick Alberelli commented 2024-05-13 16:57:58 +02:00
Member
Copy Link

Thanks for the feedback.

Here the link points to https://flamenco.blender.org/usage/shared-storage/shaman/#how-does-it-work, which effectively makes the reader skip the table of contents and the introduction. It would be better to just link to the page itself, and not any specific header.

I have gone ahead and updated this link in the documentation in this commit

A storage location is never absolute or relative. It's the reference to that location that can be absolute / relative. I personally wouldn't know what "If you are storing your Blender executable at a relative path would mean. Probably because I'm not familiar with the rest of the TD guide ;-)

The line above the one you are qouting reads "If you followed the TD Setup Guide exactly and your project/blender executable is relative to the home folder", but it was in a warning box, so your critism is still valid, and I need to improve that statement. I have clarified this statement in this commit

AFAIK this is not how the Blender Studio artist machines are set up. I would also strongly recommend against placing the Flamenco add-on in the project-specific directory, for the same reason that's written below that sentence (the version being farm dependent).

I think it would be better to first describe the approach we use at the studio (not sure which approach that is exactly, but I suspect it's going via the Gentoo build server), as that works pretty well for us in practice. And then as a special case describe the per-project approach, where the description and the warning are in the same block of text so that they're visually closely related.

Per the Overview Page for the "Project Tools" we are talking about everything is on a per project basis. I understand your strong recommendation not to distribute add-ons this way but this is how the toolset (as directed by Francesco) works. Everything is done per project in an effort to lower the barrier to entry for using the pipeline. To address your concern I did include a warning about versioning.

Using Gentoo isn't considered a required step in rolling out a "Blender Studio Pipeline", and has been moved to it's own section, seperate from the "Project Tools". Which already has documentation about how to update addons . I have linked to that page from the Flamenco page in this commit

All of the changes discussed above are live at https://studio.blender.org/pipeline/td-guide/flamenco_setup please let me know if there is any other feedback otherwise we can close this issue.

Thanks for the feedback. > Here the link points to https://flamenco.blender.org/usage/shared-storage/shaman/#how-does-it-work, which effectively makes the reader skip the table of contents and the introduction. It would be better to just link to the page itself, and not any specific header. I have gone ahead and updated this link in the documentation in [this commit](https://projects.blender.org/studio/blender-studio-pipeline/commit/e017548b368b2725125c00b04079de43722f0650) >A storage location is never absolute or relative. It's the reference to that location that can be absolute / relative. I personally wouldn't know what "If you are storing your Blender executable at a relative path would mean. Probably because I'm not familiar with the rest of the TD guide ;-) The line above the one you are qouting reads *"If you followed the TD Setup Guide exactly and your project/blender executable is relative to the home folder"*, but it was in a warning box, so your critism is still valid, and I need to improve that statement. I have clarified this statement in [this commit](https://projects.blender.org/studio/blender-studio-pipeline/commit/e017548b368b2725125c00b04079de43722f0650) > AFAIK this is not how the Blender Studio artist machines are set up. I would also strongly recommend against placing the Flamenco add-on in the project-specific directory, for the same reason that's written below that sentence (the version being farm dependent). > > I think it would be better to first describe the approach we use at the studio (not sure which approach that is exactly, but I suspect it's going via the Gentoo build server), as that works pretty well for us in practice. And then as a special case describe the per-project approach, where the description and the warning are in the same block of text so that they're visually closely related. Per the [Overview Page](https://studio.blender.org/pipeline/user-guide/project_tools/project-overview) for the "Project Tools" we are talking about everything is on a per project basis. I understand your strong recommendation not to distribute add-ons this way but this is how the toolset (as directed by Francesco) works. Everything is done per project in an effort to lower the barrier to entry for using the pipeline. To address your concern I did include a [warning about versioning](https://studio.blender.org/pipeline/td-guide/flamenco_setup#:~:text=artifacts/addons/%20directory.-,Versioning,-You%20will%20need). Using Gentoo isn't considered a required step in rolling out a "Blender Studio Pipeline", and has been moved to it's own section, seperate from the "Project Tools". Which already has [documentation about how to update addons](https://studio.blender.org/pipeline/gentoo/td/maintaince#update-local-add-ons) . I have linked to that page from the Flamenco page in [this commit](https://projects.blender.org/studio/blender-studio-pipeline/commit/d26a7131bb9fd236557c953620ad2f1e4e9790f6) All of the changes discussed above are live at https://studio.blender.org/pipeline/td-guide/flamenco_setup please let me know if there is any other feedback otherwise we can close this issue.
Sybren A. Stüvel commented 2024-05-15 10:24:38 +02:00
Author
Owner
Copy Link

I have gone ahead and updated this link in the documentation [...] I have clarified this statement [...]

Much better, thanks!

Per the Overview Page for the "Project Tools" we are talking about everything is on a per project basis. I understand your strong recommendation not to distribute add-ons this way but this is how the toolset (as directed by Francesco) works.

Personally I'm still unsure about how the Flamenco add-on is updated at the studio. This documentation doesn't help me with that, as it describes a different setup that what we seem to be actually using. Maybe @ZedDB can help to shed some light on this (and I think he already explained it to me, but it keeps being a bit fuzzy every time I need to update things; the update goes well, all the automation works).

Everything is done per project in an effort to lower the barrier to entry for using the pipeline. To address your concern I did include a warning about versioning.

Using Gentoo isn't considered a required step in rolling out a "Blender Studio Pipeline", and has been moved to it's own section, seperate from the "Project Tools". Which already has documentation about how to update addons . I have linked to that page from the Flamenco page in this commit

What would help, for me, is if it were explicitly mentioned in the Gentoo section that the Flamenco package also installs the add-on in a directory that's found by Blender (the Blender part I'm not sure about though). This is quite different from when you download Flamenco from flamenco.b.o, as that package does not have the add-on directly in there (you need to start the Manager and download it from there). The Gentoo package thus behaves differently than the regular download, and I think it would help if that were made explicit.

> I have gone ahead and updated this link in the documentation [...] I have clarified this statement [...] Much better, thanks! > Per the [Overview Page](https://studio.blender.org/pipeline/user-guide/project_tools/project-overview) for the "Project Tools" we are talking about everything is on a per project basis. I understand your strong recommendation not to distribute add-ons this way but this is how the toolset (as directed by Francesco) works. Personally I'm still unsure about how the Flamenco add-on is updated at the studio. This documentation doesn't help me with that, as it describes a different setup that what we seem to be actually using. Maybe @ZedDB can help to shed some light on this (and I think he already explained it to me, but it keeps being a bit fuzzy every time I need to update things; the update goes well, all the automation works). > Everything is done per project in an effort to lower the barrier to entry for using the pipeline. To address your concern I did include a [warning about versioning](https://studio.blender.org/pipeline/td-guide/flamenco_setup#:~:text=artifacts/addons/%20directory.-,Versioning,-You%20will%20need). > > Using Gentoo isn't considered a required step in rolling out a "Blender Studio Pipeline", and has been moved to it's own section, seperate from the "Project Tools". Which already has [documentation about how to update addons](https://studio.blender.org/pipeline/gentoo/td/maintaince#update-local-add-ons) . I have linked to that page from the Flamenco page in [this commit](https://projects.blender.org/studio/blender-studio-pipeline/commit/d26a7131bb9fd236557c953620ad2f1e4e9790f6) What would help, for me, is if it were explicitly mentioned in the Gentoo section that the Flamenco package also installs the add-on in a directory that's found by Blender (the Blender part I'm not sure about though). This is quite different from when you download Flamenco from [flamenco.b.o](https://flamenco.blender.org/), as that package does not have the add-on directly in there (you need to start the Manager and download it from there). The Gentoo package thus behaves differently than the regular download, and I think it would help if that were made explicit.
Nick Alberelli commented 2024-05-15 17:31:28 +02:00
Member
Copy Link

This documentation doesn't help me with that, as it describes a different setup that what we seem to be actually using.

Yes, what I was trying to point out is the Flamenco Setup Page we are discussing is part of a section that describes a different setup then what is used in the Blender Studio.

What would help, for me, is if it were explicitly mentioned in the Gentoo section that the Flamenco package also installs the add-on

That can be added but to the Gentoo section once @ZedDB clarifies how to update flamenco on Gentoo. There is already an update add-ons section for gentoo, but I am not sure if it's out of date.

> This documentation doesn't help me with that, as it describes a different setup that what we seem to be actually using. Yes, what I was trying to point out is the Flamenco Setup Page we are discussing is part of a section that describes a different setup then what is used in the Blender Studio. >What would help, for me, is if it were explicitly mentioned in the Gentoo section that the Flamenco package also installs the add-on That can be added but to the [Gentoo section](https://studio.blender.org/pipeline/gentoo/td/overview) once @ZedDB clarifies how to update flamenco on Gentoo. There is already an update [add-ons section](https://studio.blender.org/pipeline/gentoo/td/maintaince) for gentoo, but I am not sure if it's out of date.
Sebastian Parborg commented 2024-05-15 18:38:33 +02:00
Member
Copy Link

@TinyNick the flamenco addon is installed by the flamenco package as stated here:
https://studio.blender.org/pipeline/gentoo/td/maintaince#update-local-add-ons

@TinyNick the flamenco addon is installed by the flamenco package as stated here: https://studio.blender.org/pipeline/gentoo/td/maintaince#update-local-add-ons
Sybren A. Stüvel commented 2024-05-16 08:29:46 +02:00
Author
Owner
Copy Link

Personally I'd include some info in that section that that command will install all of Flamenco, and not just the add-on.

Apart from that, I think the original issue is done, the Flamenco section is now a lot clearer, thanks!

Personally I'd include some info in that section that that command will install all of Flamenco, and not just the add-on. Apart from that, I think the original issue is done, the Flamenco section is now a lot clearer, thanks!
Sebastian Parborg commented 2024-05-17 11:48:49 +02:00
Member
Copy Link

@dr.sybren I've updated the addon section clarifying what the command does.

@dr.sybren I've updated the addon section clarifying what the command does.
❤️ 1
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels   
Kind
Breaking
Breaking change that won't be backward compatible

  
Kind
Bug
Something is not working

  
Kind: Community

Issues opened by members of the community / outside the studio

  
Kind
Documentation
Documentation changes

  
Kind
Easy
Simple to complete

  
Kind
Enhancement
Improve existing functionality

  
Kind
Feature
New functionality

  
Kind
Proposal
A proposal or idea that requires feedback

  
Kind
Security
This is security issue

  
Kind
Studio Request
Requested by a user at the Blender-Studio

  
Kind
Testing
Issue or pull request related to testing

  
Priority
Critical
The priority is critical

  
Priority
High
The priority is high

  
Priority
Low
The priority is low

  
Priority
Medium
The priority is medium

  
Reviewed
Confirmed
Issue has been confirmed

  
Reviewed
Duplicate
This issue or pull request already exists

  
Reviewed
Invalid
Invalid issue

  
Reviewed
Won't Fix
This issue won't be fixed

  
Status
Abandoned
Somebody has started to work on this but abandoned work

  
Status
Blocked
Something is blocking this issue or pull request

  
Status
Need More Info
Feedback is required to reproduce issue or to continue work

No Label
Kind
Breaking
Kind
Bug
Kind: Community
Kind
Documentation
Kind
Easy
Kind
Enhancement
Kind
Feature
Kind
Proposal
Kind
Security
Kind
Studio Request
Kind
Testing
Priority
Critical
Priority
High
Priority
Low
Priority
Medium
Reviewed
Confirmed
Reviewed
Duplicate
Reviewed
Invalid
Reviewed
Won't Fix
Status
Abandoned
Status
Blocked
Status
Need More Info
Milestone
Clear milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
No Assignees
3 Participants
Notifications
Due Date
The due date is invalid or out of range. Please use the format 'yyyy-mm-dd'.

No due date set.

Dependencies

No dependencies set.

Reference: studio/blender-studio-tools#284
No description provided.
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?