Re: [Jython-dev] A new Jython DevGuide

[Jeff A. <ja...@fa...>]

I've finished my preliminary restructuring of the developers' guide at 
https://github.com/jython/devguide.

You'll recall that one of the prompts for this was lessening support for 
hg.python.org. We want to follow CPython and get the Jython source over 
to GitHub. For that we need a changed core development and contribution 
process, like CPython's, where everyone can read it. So far, I have:

 1. Stolen CPython's text and structure.
 2. Assessed which pages work for us unchanged or with only minor change.
 3. Made parallel pages (name_jy.rst) where the content differs widely.
 4. Integrated Frank's Jython-specific text from the current devguide
    into those and some unique pages.
 5. Added a bit of content myself.
 6. Contributed a few technical improvements upstream to the CPython
    devguide.
 7. Merged changes from the upstream CPython devguide (not just mine)
    into the Jython devguide.

The merge was not totally painless, but only 3 files gave me conflicts. 
It took a couple of hours with kdiff3, and working carefully from the 
Git Book. It's feasible, but there may be a better way. Two of these 
files had a lot of differences. Somehow kdiff3 seemed to guess correctly 
nearly everywhere.

Could we think about how we publish this so it becomes a functional 
replacement for http://www.jython.org/devguide ? It is not ready yet, 
but if we all think it will be, then the question becomes how. I could 
set up publishing to readthedocs (on my own account), but do we have a 
Jython/PSF one? Or is it better to take the html to jython.org as we 
have previously?

It was nice to see my PRs to the CPython guide, once accepted, go live 
on docs.python.org within hours. I assume this happens automatically. 
That's to aim for, I think, creating one decision point (the PR 
acceptance) and giving the rest of the job to machines.

Jeff

Jeff Allen

On 04/10/2017 19:27, fwi...@gm... wrote:
> Hi Jeff,
>
> http://www.jython.org/devguide/ is produced from a fork of the CPython
> devguide - though clearly it's really out of date. The repo is here:
> https://hg.python.org/jython-docs/devguide/
>
> Thanks for looking at this!
>
> On Sat, Sep 30, 2017 at 8:59 AM, Jeff Allen <ja...@fa...> wrote:
>> I created a repository in the project space on GitHub that is a clone of the
>> CPython devguide: https://github.com/jython/devguide
>>
>> The idea is to draw on the good work done recently (and still being done) by
>> CPython to define process and conventions for working on GitHub, which is
>> where, we've noted, we need to move. They've blazed a trail we'd be daft not
>> to follow wherever we can, and they have tools. In any case, that which is
>> not just process is also largely:
>>
>> Guidelines we refer to already;
>> Advice we should probably follow; and
>> Things mandatory on a PSF project.
>>
>> I'm hoping this will give us a much clearer reference for contributors, for
>> less work than maintaining those sections of the Jython wiki. If you visit
>> the CPython core developer part of the wiki it has been reduced to link into
>> the devguide. I suppose ours would go on jython.org eventually?
>>
>> I'm not sure how this will work: e.g. do we create name_jy.rst parallels;
>> can we edit mechanically; and is the Jython version on the master branch or
>> another? I've already done some deleting and re-making branches. So I'll
>> just try it and find out. At the moment I'm classifying chapters on a scale
>> of "irredeemably C-specific" through to "just as true for Jython". There are
>> not as many at the latter end as I'd hoped.
>>
>> The first outcome has been a minor contribution to the CPython version: to
>> make it build on Windows. This puts me on the contributing end of the
>> GitHub-based process as practised, which is a useful experience. I'm finding
>> review is very ... active :)
>>
>> Jeff
>>
>> --
>> Jeff Allen