Hi Gabriel, Gabriel Wicki <gabr...@erlikon.ch> writes:
> Aloha! > > Inspired by the `ChangeLog deprecation' and `minimal requirements for > committing changes' discussions i came to the conclusion that to help > possible newcomers with their on-boarding experience as contributors an > important step would be to update our documentation to more concisely > reflect how we do the things we do. > > Taking a closer look at the Contributing chapter in our reference manual > i found it to have grown historically and in need of some tidying up. > While it holds a vast treasure of important knowledge it could use some > (re-)structuring, some updates and some extensions. > > I am looking forward to crafting patches in this regard, but first i > would like to hear some opinions. > > > My suggestions can be summarized as follows: > > 1. Hierarchical structure > > I think we should re-arrange the information in more easily digestible > hierarchies. Maybe 3 main points with a hierarchical depth of maybe > three layers down? See further down for a rough draft of headlines > > 2. Informal contributions > > I think it would be important to not only restrict the information there > to coding and the related fields, but also towards other fields where a > project like this needs contributions and voluntary work (summarized in > the excerpt below). > > 3. Split general information from how-to guides > > I think the manual would profit if we split concrete how-to kind of > information into sections in our cookbook (and cross-reference in both > directions). I guess for the cookbook a more-is-more approach is fine > whereas in the manual a factually correct, important and concise > information approach shall rule. > > 4. Project description > > I think it would serve the project as a whole and potential contributors > specifically if we describe the organizational structure of this project > so people can more easily find ways through the forest of people, > instances, roles and responsibilities we have grown to represent and be > more explicit on the opportunities for people to take responsibility for > the project. > > I suggest to add a chapter to the manual that explains our > Organizational Structure and add a section in the Contributing chapter > on how to take responsibility. > > 5. Update and enrich information > > And finally i think we could update sections like `how to style commit > messages' with our de-facto usage in Guix and add some examples, the > Tracking Bugs and Changes seems to need some work so it reflects the > Codeberg infrastructure, etc. > > Also, i think the Contributing chapter of our manual could be more > specific in leading people up to the point where they can actually > contribute. This could entail: > > - how to file bug-reports (specific example), > - how to reproduce a bug, > - how to bisect git history to find which commit introduced some bug, > - how to upgrade a package, etc. I think that's a valuable effort, especially in light of the recent change to Codeberg (so some documentation needs updating as you mentioned). > > > Below you can find a draft of the information hierarchy i imagine for > the Contributing chapter. I tried to take all the existing parts of the > current contributing.texi into account and fill it into the hierarchy > hoping to order information as naturally and logically as possible. > > --8<---------------cut here---------------start------------->8--- > > * Informal Contributions > > Developing a project like GNU Guix is not only about hacking, coding and > system administration - much time and effort is spent in informal > contributions. > > Important informal contributions include: > > - helping others via chat, mailing lists or on codeberg, > - reporting issues you find, > - testing stuff others ask you to, > - reviewing other contributions (and if you have specific interests: > join a team!), > - translating Guix to a language you know, > - discussing topics that are currently decided upon. > > Chime in, take part and share your experience - we are keen to get to > know how we can enhance it further and welcome you on board! > > => link code of conduct and GNU Kind Communication Guidelines > > => expand or link some of the points above in their own dedicated > section (e.g. leave Translating Guix as is, link to cookbook recipes on: > how to review, how to report issues, etc) > > * Formal Contributions > > Formal contributions entail documentation as well as code and include > pointers on where to find work to contribute as well as what to keep in > mind when doing so. > > ** Necessary Knowledge for Formal Contributions > Either here or with links to cookbook recipes (since all these points > are how-tos). > > *** how to build guix > **** how to run the test suite from checkout > **** how to build the docs from checkout > **** how to build a specific package from checkout > **** how to build a system configuration from checkout > > *** Source Tree Structure > Leave as is > > ** Writing Documentation > Leave as is > > ** Hacking Guix > How to contribute with code > > This section shall include: > - How to fix stuff > Where to find bugs to fix, approaches one can take to try to fix stuff. > - How to add a new package (incl. Packaging Guidelines) > - How to update package definitions > incl. what to look out for, leaf packages vs. dependencies, link to > commit message section Maybe these guide-like example should appear in the Cookbook instead? > ** Contribute formal work > *** Notes on style and language > Programming and natural language(s), paradigms, coding style, etc. > > *** Sharing your work > Split up changes into logically connected commits / How to open a Pull > Request / Which branch to merge changes into, etc. > > *** Commit messages > Brief explanation of commit message style (reference to ChangeLog for > historic reasons). > > Include examples for simple changes (new package, package version bump, > new service, one or two other types of message). The idea is that a > newcomer can easily take inspiration from the manual and streamline > their change set swiftly and easily > > * Take Responsibility > > Inviting section explaining how projects of this scale can only work > when volunteers take responsibility (and how taking this responsibility > yields valuable karma in the spirit of the GNU) > > Maybe with a short note on responsibility and trust? > > ** Partake in Decision Making > Partake in discussions, explain GCD, etc. > > ** Join a Team > What teams are for and how to join them (is there even a defined > process?) > > ** Become a Committer > How to get there and what this role entails > --8<---------------cut here---------------end--------------->8--- > > > What do you think? I like your initiative! I'd like to encourage you to persevere in this effort and would be happy to review. -- Thanks, Maxim
