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.
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.
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. :)