<dc:creator>GNU social development team</dc:creator>
<pubDate>Fri, 13 Aug 2021 13:37:42 +0100</pubDate></item>
<item><title>
Updates: Improve the Attachments system
</title><description><![CDATA[
<p>With the milestone "Port Media system from v2" we had ported the existing
attachment system. The fact is that this system wasn't good enough.</p>
<p>It's always important to start with the original code as that allows us
to review past decisions and understand all the corner cases.</p>
<p>Sadly, what motivated us to re-design the attachment system was the
non-considered corner cases.</p>
<p>Key commits:</p>
<ul>
<li><ahref="https://code.undefinedhackers.net/GNUsocial/gnu-social/commit/32ad5dbd74ebb369c4b3ed688e1fb78464fabe49">32ad5dbd74 - [ENTITY] Split Attachment in various new entities</a></li>
<li><ahref="https://code.undefinedhackers.net/GNUsocial/gnu-social/commit/c381e58d3307e7dd07abeb9cf5b3998e34f5bd48">c381e58d33 - [ENTITY] Refactor RemoteURL entities to Link</a></li>
</ul>
<p>The reasoning leading to these entities and structure is detailed in our
<p>GNU social now has its documentation available in
<ahref="https://docs.gnusocial.rocks/">https://docs.gnusocial.rocks/</a>. It features four
different books. It is automatically generated from the <ahref="https://code.undefinedhackers.net/GNUsocial/gnu-social/src/branch/v3/docs">source</a> using <ahref="https://rust-lang.github.io/mdBook/">mdBook</a>.</p>
<p>Only the development book is in an elaborated state, the other books are
holding for more ready code.</p>
<p>Two of them are updates from existing documentation:</p>
<ul>
<li>The <ahref="https://docs.gnusocial.rocks/user">User</a> one is adapted
from the existing GNU social documentation for users that was provided in v2.</li>
<li>The <ahref="https://docs.gnusocial.rocks/administrator">Administrator</a> one is adapted
from the "Unofficial GNU social docs" by Thomask who <ahref="https://notabug.org/diogo/gnu-social/issues/246">asked us to make it official</a>.</li>
</ul>
<p>And two of them are new:</p>
<ul>
<li>The <ahref="https://docs.gnusocial.rocks/developer">Developer</a> is both intended to guide third-party plugin developers and to make it easier of contributing to the code.</li>
<li>The <ahref="https://docs.gnusocial.rocks/designer">Designer</a> is the most recent of the four and came from a necessity of keeping some standardization between templates and ensuring the same principles are kept in mind when designing new themes.</li>
</ul>
<p>Together with the documentation we've introduced a
<ahref="https://agile.gnusocial.rocks/">wiki</a>. Its purpose is to walk-through decisions,
convention, terminology. It's where we document the reasoning the dev team went
through before implementing more sophisticated functionalities.</p>
<p>Finally, when the documentation doesn't explain, and to ensure the whole code
is properly tested, we have the
<ahref="https://code.undefinedhackers.net/GNUsocial/gnu-social/src/branch/v3/tests">tests</a>. And the coverage is available <ahref="https://coverage.gnusocial.rocks/">here</a>.</p>
<p>File Storage in GNU social is used for avatars, for notes containing
attachments, and for notes containing links (in which case is an Embed preview).
Notes can be created by local users or fetched from remote actors. Filehash is
used to reduce file duplication.</p>
<p>When a user shares a Link that uses OpenGraph tags or has an OEmbed provider,
the <ahref="https://code.undefinedhackers.net/GNUsocial/gnu-social/src/branch/v3/plugins/Embed">Embed plugin</a> generates a preview for it that may contain a thumbnail.</p>
<p>When a user shares a Link to an image, the <ahref="https://code.undefinedhackers.net/GNUsocial/gnu-social/src/branch/v3/plugins/StoreRemoteMedia">StoreRemoteMedia plugin</a> can fetch the
file and make it available as an attachment, and will generate a thumbnail.</p>
<p>When an image, video, or other file type is uploaded or retrieved, an Attachment
entity is created. When a thumbnail is requested, one is generated.</p>
<p>There are three relevant plugins for attachment handling:</p>
<ul>
<li><ahref="https://code.undefinedhackers.net/GNUsocial/gnu-social/src/branch/v3/plugins/ImageEncoder">ImageEncoder</a>: Allows to compress, validate, rescale, and sanitize images using VIPS.</li>
<li><ahref="https://code.undefinedhackers.net/GNUsocial/gnu-social/src/branch/v3/plugins/VideoEncoder">VideoEncoder</a>: Allows to compress, validate, rescale, and sanitize videos using FFMpeg.</li>
<li><ahref="https://code.undefinedhackers.net/GNUsocial/gnu-social/src/branch/v3/plugins/FileQuota">FileQuota</a>: Ensures a user stays under the file quota.</li>
</ul>
<h2>How is the code organised?</h2>
<p>There are various entities related to attachment, and thumbnail handling.
