Hi all, Here's the link to the checklist https://live.gnome.org/sindhus/SuggestedWorkflowForWritingUserHelp
Hope it helps. -Sindhu On Mon, Apr 22, 2013 at 2:29 AM, Ekaterina Gerasimova < [email protected]> wrote: > Hi (again) Petr, > > On 2013-04-21 20:04, Petr Kovar <[email protected]> wrote: > >Ekaterina Gerasimova <[email protected]>, Thu, 18 Apr 2013 18:08:08 > >+0100: > >> On 18 April 2013 16:12, Petr Kovar <[email protected]> wrote: > >> > >> I suggested that Jana work in a branch (which I recommended that she > name > >> in a way that made it clear that it was her personal playground) for two > >> reasons: > >> - She pushed incorrect instructions to master for internal Red Hat > builds > > > >I'm not quite sure what do you mean by "internal Red Hat builds". We > >don't use any "internal Red Hat builds" to document GNOME. ;-) > > Jana told me that she needed to push her patches to git so that the > pages can be built for her work; I am just going by what I was told :) > > >I wish we had a review process more friendly to newcomers, as dealing with > >git patches and having to redo them in case the previous patch was > rejected > >can get cumbersome rather quickly. > > > >With my translator hat on, I have to say our translators also have to > learn > >the git basics at some point, but with the submission process on > >10n.gnome.org, they can at least focus more on what really matters (that > >is, translating) than the technicalities of workflow processes originally > >designed for developers in mind. Just my 2 cents. > > There are tools which can simplify the workflow. For example, git-bz can > automate the formating of the patch and uploading it to Bugzilla. > > Personally, I am happy to fixup fly-by patches. On the other hand, if > someone is contributing significantly, as is the case in this specific > instance, then I consider that it is good practice to teach them how to > contribute well, because fixing up poor patches often takes more of my > time than helping someone perfect their contributions to the point where > they no longer need reviews. > > >I understand that development - in many cases - happens on master. Since > >there is no gnome-3-8 branch and upcoming stable releases will probably be > >released directly from master, I don't feel quite comfortable writing a > >guide, which is under heavy development, on master. This is exactly why I > >proposed working in a wip branch. > > There are a few "safe" methods of working on master that you may want to > consider: > - If you are using it as a backup for your work while updating an existing > page, then the unfinished content can be quoted out until it is complete > using <!-- and -->. > - New pages can be named *.page.stub: these are not displayed if yelp is > given a path to that directory and are not included in the tarball when > the module is released. > > Stubs and quoted out content cannot break validation, nor the build. > > >> > Before one of the next stable releases (.2/.3?), we can then rebase > the > >> > branch on top of master. > >> > > >> > Are you OK with this workflow? > >> > >> Do you have a good reason for working this way? Rebasing a branch can > take > >> a lot of effort and time. Development should be on master, but it's > >> important that the quality of the documentation is maintained in the > >> process. > > > >Have a look at various GNOME modules, developers use wip branches > >extensively. If that worflow works well for developers, I think it should > >also work for documentation writers. > > On git.gnome.org, the whole point of branches prefixed with wip/ is that > they can be rebased. Coordinating rebases between a group of people is > difficult (which is why these types of branches are usually used for > solitary development), especially if some of those people are not > comfortable with using git. This is also not compatible with simplifying > workflow for new contributors as they would have to learn distributed > development at the same time as the basics. This is something that I > make an effort to acquaint my Outreach Program interns with, but most > are not ready for it until the end of their third month of working with > git, so this is not something that I can honestly expect first time > contributors to deal with. > > >> On that subject, 3.8.2 is due for release on the 13th of May, which is > >> only 3.5 weeks away, and there has not been much activity in fixing > those > >> incorrect instructions that I mentioned earlier. There are even some > >> "accepted - commit now" patches on Bugzilla, waiting to be committed, do > >> you know when these will be looked at? > > > >I would prefer to have most of our planned topics documented for .3, but > >this will take some time, since as per > https://live.gnome.org/SysAdminGuide > >there appear quite a few topics that are yet to be covered, so the May > >deadline for all the tasks seems to be too optimistic. I plan to look at > >those as well, anyway. > > While I was referring only to the recent changes, in general, it may be > easier to deal with the topics if they are taken on one at a time. I > know that it may sometimes take a while for reviews to happen, but it > would help if due diligence was taken to make sure that the patches were > technically correct. Sindhu wrote a number of posts as part of her > internship which contained checklists of common pitfalls that we both > came across while she was being mentored as a new contributor. > > _______________________________________________ > gnome-doc-list mailing list > [email protected] > https://mail.gnome.org/mailman/listinfo/gnome-doc-list > >
_______________________________________________ gnome-doc-list mailing list [email protected] https://mail.gnome.org/mailman/listinfo/gnome-doc-list
