Hi (again) Petr,
On 2013-04-21 20:04, Petr Kovar <
pmkovar gnome org> wrote:
>Ekaterina Gerasimova <
kittykat3756 gmail com>, Thu, 18 Apr 2013 18:08:08
>+0100:
>> On 18 April 2013 16:12, Petr Kovar <
pmkovar gnome org> 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.
