Bug 570938 – New wiki page for new/occasional contributors

• Product: Documentation
• Status: RESOLVED INVALID

[Description augustin 2016-01-05 07:30:31 UTC]

I am a gentoo newbie who would like to learn how to contribute code. As a newbie and a would-be first time contributor, I found that there was a lack of documentation, as explained below. I am willing to help create such a document on the wiki. I wanted to discuss this with the developer community to get some feedback on this proposal.

I wanted to contribute a patch, my first, for a version bump to this ebuild: 
https://bugs.gentoo.org/show_bug.cgi?id=570814 

I spent some time reading the developer documentation, including all the following pages which I have bookmarked:
https://wiki.gentoo.org/wiki/Contributing_to_Gentoo
https://wiki.gentoo.org/wiki/Basic_guide_to_write_Gentoo_Ebuilds
https://wiki.gentoo.org/wiki//etc/portage/patches
https://wiki.gentoo.org/wiki/Submitting_ebuilds
https://www.gentoo.org/inside-gentoo/developers/
https://www.gentoo.org/get-involved/become-developer/
https://www.gentoo.org/get-involved/contribute/
https://www.gentoo.org/get-involved/get-code/
https://devmanual.gentoo.org/
https://devmanual.gentoo.org/ebuild-maintenance/index.html
https://devmanual.gentoo.org/ebuild-writing/index.html
https://devmanual.gentoo.org/quickstart/index.html

Sam Jorna, in the aforementioned bug, also mentioned this page, which, despite my thorough research, I had not yet found:
https://wiki.gentoo.org/wiki/Project:Proxy_Maintainers 

Despite all the excellent documentation above, I feel that there is a need for another document to help gentoo newbies and potential new contributors like me get up to speed.

The target audience for the document would be:
- New gentoo users.
- Users who would like to learn how to contribute patches to existing ebuilds, or create new ebuilds.
- Users who do not necessarily want to commit themselves to become a full fledged gentoo developers, or maybe not even a proxy maintainer. Let's not scare potential contributors away by asking them to commit. Simply help them to contribute their first patch.

The document would:
- provide a full outline going from being a simple gentoo user (having gentoo up and running) to being a first time gentoo contributor.
- at each step along the way, provide a list of links to existing, more detailed documentation.

Steps to cover:
- providing an overview of the quality requirements for ebuilds, etc.
- providing an overview of the usual process for contributing to gentoo.
- creating an overlay for local development.
- getting an anonymous checkout of the gentoo tree, from which to create patches.
- understanding the existing ebuild, with pointers to what needs to be done to add a new patch to the ebuild, to create a new version, etc.
- testing the ebuild locally, in a safe manner (i.e. explaining how to revert changes should the newbie break her own environment)
- creating a patch and submitting it to the bug tracker.
- how to get attention to the patch, which developers or herds to contact.
- for those new contributors who would consider committing themselves a bit more, link to the proxy manager documentation, and provide a brief outline (with links to existing documentation) on the path to becoming a fully fledged gentoo developer.


Link to existing documentation related to:
- ebuilds, emerge, portage.
- overlays
- gentoo community
- gentoo developer documentation
- git checkout, patches.
- submitting bugs,
- etc.

[Comment 1 augustin 2016-01-05 07:43:18 UTC]

Ironically, the most helpful, simple, HOWTO that I found and which covers part of what I propose above, was not found on gentoo.org:

Using custom ebuilds with Gentoo
http://linuxreviews.org/gentoo/ebuilds/ 

So the wiki document I suggest should at the very least cover the steps mentioned in the above article.

I'm sure I have missed relevant documentation here. We simply need to make them easier to discover for new comers.

[Comment 2 augustin 2016-01-05 08:25:11 UTC]

Note: do not burden the new contributor with information about deprecated features. (e.g. PORTDIR_OVERLAY). Lead them straight to the newest preferred method of doing things (e.g.  repos.conf style changes).

[Comment 3 Adam Feldman 2016-01-05 08:26:33 UTC]

(In reply to augustin from comment #0)
> I am willing to help create such a
> document on the wiki. I wanted to discuss this with the developer community
> to get some feedback on this proposal.


I think you are better served by firing off an email to the dev ML and stating that you want to help improve documentation and would like a RFC and assistance where applicable.  I suspect you'll get a more productive conversation that a bug on bugzilla.

[Comment 4 Alex Legler (RETIRED) 2016-01-05 12:19:11 UTC]

(In reply to NP-Hardass from comment #3)
> (In reply to augustin from comment #0)
> > I am willing to help create such a
> > document on the wiki. I wanted to discuss this with the developer community
> > to get some feedback on this proposal.
> 
> 
> I think you are better served by firing off an email to the dev ML and
> stating that you want to help improve documentation and would like a RFC and
> assistance where applicable.  I suspect you'll get a more productive
> conversation that a bug on bugzilla.

Indeed. Wiki and bugs don't go well together.
You can always go right ahead and create a page in your user space and start working on the outline and contents of what you imagine. When you need help and/or input, do ask the list, wiki and docs team.

As this doesn't make sense to be tracked as a bug, I'll close it, but do go on about implementing your idea with the resources we pointed out above.

[Comment 5 augustin 2016-01-05 13:17:05 UTC]

Thank you NP-Hardass  and Alex.
:)