Hi all,
After some time since the board entries were moved to the doxygen documentation [1], we are facing the problem on where to put board pictures.
I see 2 cases:
- We don’t have the rights to distribute the picture.
- The responsible of the board has the ownership of the picture
For 1. I propose to keep what we have been doing and add deep-links to the board manufacturer (e.g [2])
For 2. some options:
- Put them in the RIOT repo under <board_name>/doc
- Put them in a folder in the RIOT wiki
- Put them in a separate RIOT-OS doc repo
I personally think 2. (put them in the RIOT wiki) is the fastest way to go and doesn’t bloat the RIOT repository. But I would like to hear some comments about this topic.
When we find consensus, I will update the Porting Guide [3] to indicate where to store the files.
Cheers,
José
[1]:
[2]:
[3]:
If we put them in the RIOT wiki we can always choose to move them to the repo if it proves problematic. The other way round (moving them out of the repo) will leave a permanent blob in git's history.
How about git-lfs?
WRT another doc repo, I think documentation and code belong together.
Regards,
Juan.
Hi!
Hi all,
After some time since the board entries were moved to the doxygen
documentation [1], we are facing the problem on where to put board pictures.
I see 2 cases:
1. We don't have the rights to distribute the picture.
2. The responsible of the board has the ownership of the picture
How problematic/complicated is it to ask the owners of the pictures if we
can use them? (I have no idea, so maybe my question is not super valid) I
guess it would be a matter of publishing the picture with a copyleft
license.
I mean this because that would ease the way we treat them. I’d say if we
support a board from which we already have schematics and lots of other
information which is open, then a picture seems for me the least of the
protected information.
Cheers,
Paco.
Hi all,
Thank you for your responses!
So, it seems we are converging to have them close to the code (RIOT repo). I will give a look to git-lfs in the meantime.
How problematic/complicated is it to ask the owners of the pictures if we
can use them? (I have no idea, so maybe my question is not super valid) I
guess it would be a matter of publishing the picture with a copyleft
license.
I mean this because that would ease the way we treat them. I’d say if we
support a board from which we already have schematics and lots of other
information which is open, then a picture seems for me the least of the
protected information.
I agree with this and maybe it's not that problematic to ask the owner of the pictures. Some other platforms are hosting pictures in their own website, so I think it's possible.
Cheers,
José
Hi all,
git-lfs looks promising and seems to be used by other projects. It would really help with a not-bloated RIOT repo. The only issue is the fact git-lfs has to be installed in order to interact with the files (commands like `make doc`) won't pick the images because they will be sort of symlinks.
Are the benefits greater than the drawbacks? If so, I can open a PR.
Cheers,
José
Most users don't run make doc. It's run by the static checks, but only to verify docstrings are OK. In that case, we can ignore warnings caused by the missing images (option A).
Another option is to instruct users to sync the LFS (B), or to do it automatically (C).
I like (B) better.
Regards
Juan.
Hi all,
Check this attempt [1] using git-lfs. It also uses "a hidden repo" like the wiki, but it's transparent to the developer.
Cheers,
José
[1]: https://github.com/RIOT-OS/RIOT/pull/9818
Hi all,
I just discovered users cannot push directly in the RIOT.wiki repository (only via the web interface, which doesn't allow to push images unless a new entry is created).
This adds some complexity because maintainers would need to put the pictures there (and ask users to hardcode the `https://raw.githubusercontent.com/wiki/RIOT-OS/RIOT/images/` prefix to their Doxygen pictures).
Is this ok for all?
Cheers,
José
Hi Jose,
last week, when I wrote the documentation for the ESP8266 boards, I had
to realize, that I had to change some pictures several times during the
documentation process.
I think the wiki approach to ask the maintainers everytime is quite
impractical:
1. Maintainers are additionally burdened with the work
2. As the developer I can't check the doxygen with images before the
pictures are placed in the wiki.
3. Your plan was to remove the wiki.
So I decided to create a GitLab repository that I can control by myself
to place my pictures there.
In the end, it should not matter which git repository is bloated.
Maybe it would be better following your suggestion, to place your own
pictures where the documentation is, i.e., in the directory
board/<board_name>/doc?
Regards
Gunar
Gunar, Jose
>
> In the end, it should not matter which git repository is bloated.
>
What about NO repository gets bloated?
This was already discussed with some other maintainers offline, but I want to reinstate it here:
We are not *special* in any way. Compared to other projects, RIOT OS does not have any crazy wacky requirements or limitations, and we are facing similar issues, for which- after similar sufferings- specialized tools were developed. Then why do we insist in doing things differently?
I'm talking about git-lfs. This tools was invented to overcome all those issues we are mentioning in this thread. To me it is the only non-hacky solution. The only time a user will be exposed to the tool will be when building/editing the docs.
git-lfs does not bloat the repo because binary blobs are not stored in there, and only the needed versions for the commits you are checking out are downloaded (not the entire diff history as with a regular text file.)
Really, all this wiki-as-object-storage thing feels like hammering a nail with a screwdriver. If we go with the hacky solution we will regret it later when we have to maintain the mess.
Regards,
Juan.
Hi Juan,
every approach which is not bloating a git repository is surely the best
one. IMHO, it is important that the approach gives the board developer
the possibility to upload/update pictures without involving maintainers.
Would it also be possible with git-lfs to give the board developers
access rights to upload pictures?
Regards
Gunar
Hi all,
Ideally, the pictures and figures should be part of the pull request
to add the board configuration, to make reviewing easier for
maintainers. Having the maintainers to upload the pictures manually of
a proposed board is too much extra administration and will steal
maintainer focus from other areas. I have no experience with git-lfs,
but maybe someone on this list can answer: Does git-lfs let the
contributor include the pictures and other git-lfs blobs as part of a
Github pull request?
/Joakim
Hi Juan, Gunar (and Joakin who just wrote).
Agreed!
Just a side note here, the scope is (so far) the boards documentation. There might be still some parts that make sense to keep them in the wiki.
I totally agree with this for several reasons:
-
Doesn’t require maintainers at all to put pictures somewhere (only make sure the uploaded picture is a git-lfs symbolic file instead of an actual image file)
-
It’s quite standard and supported natively by GitHub (both on displays in their web interface and the hidden repo they provide for LFS).
-
After installing git-lfs (Windows, Mac OS and Linux), the user “transparently” puts pictures in the doc folder. The push hook will make sure they get into the hidden repo.
-
The clone command only get the symlinks. If someone doesn’t want to build the documentation with pictures, then just don’t call git lfs pull (handled automatically in make doc in this PR [1])
And last but not least:
- It’s extremely easy to revert if we don’t like the solution.
Only the picture. The git push command with git-lfs installed will automatically upload the blob to the GH lfs repo and will replace the file with the symlink.
Cheers,
José
[1]:
Gunar, Joakim
>>
>> Would it also be possible with git-lfs to give the board developers
>> access rights to upload pictures?
>>
With LFS it will work as with a regular file, and one would need to open a PR to add/change a picture. I would expect such PRs to be approved almost immediately.
Hi all,
It seems there's a trend with storing the img files close to the code instead of using an external repo (wiki, etc). I will refactor [1] and continue the discussion there.
All comments and feedback are appreciated.
Cheers,
José
[1]: https://github.com/RIOT-OS/RIOT/pull/9818
1 Like