Bug 585218 – improvement of "What (not) to put in the Portage tree"

• Product: Documentation
• Status: RESOLVED FIXED

[Description Jonas Stein 2016-06-06 19:39:12 UTC]

I suggest to change the section
=================================
In general, the Portage tree should only be used for storing .ebuild files, as well as any relatively small companion files, such as patches or sample configuration files. These types of files should be placed in the /usr/portage/mycat/mypkg/files directory to keep the main mycat/mypkg directory uncluttered. Exceptions to this rule are for larger patch files (we recommend this for patches above 20KB) which should be distributed as tarballs via the Gentoo mirror system so that people do not waste excessive amounts of bandwidth and hard drive space. Also, you should not add binary (non-ASCII) files to the git tree. Also, speaking of merging changes, any patches you add to Portage should generally not be compressed. This will allow git to merge changes and correctly inform developers of conflicts. 
=================================

to:
==========================================

The Portage tree should only be used to store .ebuild files, as well as small  companion files (< 20 kB), such as patches or sample configuration files. All files in the tree should be uncompressed plain text.

Companion files with a size of < 20 kB should be placed in /usr/portage/mycat/mypkg/files directory larger files should be stored on the developer space on the gentoo server or other public accessible space. 

This will save memory, improve the performance of our repository and allow git to merge changes and inform developers of conflicts.
=================================

for clarification.


Reproducible: Always

[Comment 1 Ulrich Müller 2020-01-24 17:09:08 UTC]

Sorry about the long delay. How about this instead:

<p>
The Gentoo repository should only be used for storing <c>.ebuild</c> files, as well as any relatively small companion files, such as patches or sample configuration files. These types of files should be placed in the <c>mycat/mypkg/files</c> directory, which can be referenced as <c>${FILESDIR}</c> from within ebuilds. Larger patch files (we recommend this for patches above 20 kB) should be placed in your developer space on <c>dev.gentoo.org</c> instead, in order to save bandwidth and disk space for the ebuild repository.
</p>

<p>
Also, you should add only uncompressed plain text files (i.e., no binaries) to the repository. This will allow git to merge changes and correctly inform developers of conflicts.
</p>

[Comment 2 Ulrich Müller 2020-02-28 10:54:44 UTC]

(In reply to Ulrich Müller from comment #1)
> this for patches above 20 kB) should be placed in your developer space on

This should probably be 20 KiB, corresponding to an integer multiple of the common 4 KiB block size.

[Comment 3 Ulrich Müller 2020-03-01 11:43:44 UTC]

After further discussion with jstein, we come up with the following text:

<p>
The Gentoo repository should only be used for storing <c>.ebuild</c> files, as well as any small companion files, such as patches or sample configuration files. These files should have a size of at most 20 KiB and must be placed in the <c>mycat/mypkg/files</c> directory, which can be referenced as <c>${FILESDIR}</c> from within ebuilds. Larger patch files should be placed in your developer space on <c>dev.gentoo.org</c> instead, in order to minimize the repository size.
</p>

<p>
The files in the repository should be uncompressed plain text files, i.e., no binaries. This will allow the version control system to merge changes and correctly inform developers of conflicts.
</p>

I am going to merge this tomorrow, unless there are further comments.

[Comment 4 Larry the Git Cow 2020-03-02 10:49:42 UTC]

The bug has been closed via the following commit(s):

https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=5161bfd22b3d53941986b7c55ca7c3c06e54a470

commit 5161bfd22b3d53941986b7c55ca7c3c06e54a470
Author:     Ulrich Müller <[e-mail]>
AuthorDate: 2020-03-02 10:46:32 +0000
Commit:     Ulrich Müller <[e-mail]>
CommitDate: 2020-03-02 10:46:32 +0000

    ebuild-maintenance/new-ebuild: Update "What (not) to put in the tree".
    
    Closes: https://bugs.gentoo.org/585218
    Reported-by: Jonas Stein <[e-mail]>
    Signed-off-by: Ulrich Müller <[e-mail]>

 ebuild-maintenance/new-ebuild/text.xml | 27 +++++++++++++--------------
 1 file changed, 13 insertions(+), 14 deletions(-)