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:
I spent some time reading the developer documentation, including all the following pages which I have bookmarked:
Sam Jorna, in the aforementioned bug, also mentioned this page, which, despite my thorough research, I had not yet found:
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.
- gentoo community
- gentoo developer documentation
- git checkout, patches.
- submitting bugs,
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
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.
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).
(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.
(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.
Thank you NP-Hardass and Alex.