Re: [ANNOUNCE] GHC 8.6.4 is now available

2019-03-05 Thread Alan & Kim Zimmerman
I'm impressed, 'stack setup 8.6.4` brings it down already.

Alan

On Tue, 5 Mar 2019 at 23:58, Phyx  wrote:

> Thanks! To be fair I'm not really sure how popular it is. I was wondering
> since once I upload the chocolatey packages it's immutable.
>
> If there's anything I can help with let me know.
>
> Cheers,
> Tamar
>
> On Tue, Mar 5, 2019, 21:47 Ben Gamari  wrote:
>
>> Phyx  writes:
>>
>> > Hi Ben,
>> >
>> > Thanks for the release! I was wondering, any reason for the no i386
>> Windows?
>> > Should I just create the package without it or is it coming?
>> >
>> This is one configuration I haven't yet had a chance to CI-ify. I was
>> hoping it would be missed but since you mention it I've gone ahead and
>> put up an attempt at fixing this (!495 [1]). It will likely take a few
>> iterations to get right but I'll try to get it sorted by the end of the
>> week.
>>
>> Cheers,
>>
>> - Ben
>>
>>
>> [1] https://gitlab.haskell.org/ghc/ghc/merge_requests/495
>>
> ___
> ghc-devs mailing list
> ghc-devs@haskell.org
> http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs
>
___
ghc-devs mailing list
ghc-devs@haskell.org
http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs


Re: [Haskell-cafe] Final steps in GHC's Trac-to-GitLab migration

2019-03-05 Thread Ömer Sinan Ağacan
This look great, thanks to everyone involved!

Some feedback:

- When I click to the "Wiki" link on the left it opens "Home" page and I don't
  know how to go to the index from there. I think we may want index to be the
  home page for the wiki?

- Redirects don't seem to work:
  https://gitlab.staging.haskell.org/ghc/ghc/wikis/commentary/rts/heap-objects

- Comparing these two pages:

  
https://ghc.haskell.org/trac/ghc/wiki/Commentary/Rts/Storage/HeapObjects?redirectedfrom=Commentary/Rts/HeapObjects
  
https://gitlab.staging.haskell.org/ghc/ghc/wikis/commentary/rts/storage/heap-objects

  The Gitlab page doesn't have images that Trac page has. Secondly, the "_|_"
  string used in the Trac page is migrated as italic "|" in Gitlab.

Ömer

Ben Gamari , 6 Mar 2019 Çar, 04:21 tarihinde şunu yazdı:
>
> Hi everyone,
>
> Over the past few weeks we have been hard at work sorting out the
> last batch of issues in GHC's Trac-to-GitLab import [1]. At this point I
> believe we have sorted out the issues which are necessary to perform the
> final migration:
>
>  * We are missing only two tickets (#1436 and #2074 which will require a
>bit of manual intervention to import due to extremely large
>description lengths)
>
>  * A variety of markup issues have been resolved
>
>  * More metadata is now preserved via labels. We may choose to
>reorganize or eliminate some of these labels in time but it's easier
>to remove metadata after import than it is to reintroduce it. The
>logic which maps Trac metadata to GitLab labels can be found here [2]
>
>  * We now generate a Wiki table of contents [3] which is significantly
>more readable than GitLab's default page list. This will be updated
>by a cron job until underlying GitLab pages list becomes more
>readable.
>
>  * We now generate redirects for Trac ticket and Wiki links (although
>this isn't visible in the staging instance)
>
>  * Milestones are now properly closed when closed in Trac
>
>  * Mapping between Trac and GitLab usernames is now a bit more robust
>
> As in previous test imports, we would appreciate it if you could have a
> look over the import and let us know of any problems your encounter.
>
> If no serious issues are identified with the staging site we plan to
> proceed with the migration this coming weekend. The current migration
> plan is to perform the final import on gitlab.haskell.org on Saturday, 9
> March 2019.
>
> This will involve both gitlab.haskell.org and ghc.haskell.org being down
> for likely the entirety of the day Saturday and likely some of Sunday
> (EST time zone). Read-only access will be available to
> gitlab.staging.haskell.org for ticket lookup while the import is
> underway.
>
> After the import we will wait at least a week or so before we begin the
> process of decommissioning Trac, which will be kept in read-only mode
> for the duration.
>
> Do let me know if the 9 March timing is problematic.
>
> Cheers,
>
> - Ben
>
>
> [1] https://gitlab.staging.haskell.org/ghc/ghc
> [2] 
> https://github.com/bgamari/trac-to-remarkup/blob/master/TicketImport.hs#L227
> [3] https://gitlab.staging.haskell.org/ghc/ghc/wikis/index
> ___
> Haskell-Cafe mailing list
> To (un)subscribe, modify options or view archives go to:
> http://mail.haskell.org/cgi-bin/mailman/listinfo/haskell-cafe
> Only members subscribed via the mailman list are allowed to post.
___
ghc-devs mailing list
ghc-devs@haskell.org
http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs


RE: [GHC] #16348: GHC HEAD regression: tyConAppArgs

2019-03-05 Thread Ben Gamari
Simon Peyton Jones via ghc-devs  writes:

> Matthew, Ben
>
> I've just received 40-odd messages like this one. It looks as if Marge
> is now sending commit messages at Trac ticket messages, which is
> great. Will that happen after the move to GitLab.
>
> Also, is this sudden wave because a whole lot of commits have now
> landed in master? Or is it somehow an old backlog stuck in a mail
> queue?
>
This happened because the GitLab -> git.haskell.org mirroring
process was stuck. Yesterday I un-stuck it which then triggered the push
of approximately 40 commits, triggering the old Trac commit notifier
which produced the messages you received.

Regarding commit notifications after we migrate:

 * Tickets will have notes added when they are mentioned by a commit
   message. As we discussed earlier, messages won't include the commit
   message text but rather only a reference to the referring commit SHA.
   For instance, this looks like [1].

   If we find the indirection between the ticket and the mentioning
   commit message to be problematic we can certainly revisit this.

 * Commit notifications will be sent to ghc-comm...@haskell.org; the
   format will change a bit but the overall content won't change.

 * Unfortunately a mention of a ticket from a commit does not produce a
   notification email. This is in my opinion a rather serious issue that
   we will need to work around since it makes closing tickets after
   merge far more painful than necessary.


> There may be some housekeeping to do, to close tickets, check
> regression tests and add pointers to the appropriate tests. Is anyone
> up for doing that?
>
Yes, I have been accumulating a sizeable queue of tickets to
sort through. I've started working through this but certainly won't
finish tonight. I have a few other obligations tomorrow but I'll try to
pick it up again later in the day.

Cheers,

- Ben



[1] https://gitlab.staging.haskell.org/ghc/ghc/issues/16260#note_173847


signature.asc
Description: PGP signature
___
ghc-devs mailing list
ghc-devs@haskell.org
http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs


Final steps in GHC's Trac-to-GitLab migration

2019-03-05 Thread Ben Gamari
Hi everyone,

Over the past few weeks we have been hard at work sorting out the
last batch of issues in GHC's Trac-to-GitLab import [1]. At this point I
believe we have sorted out the issues which are necessary to perform the
final migration:

 * We are missing only two tickets (#1436 and #2074 which will require a
   bit of manual intervention to import due to extremely large
   description lengths)

 * A variety of markup issues have been resolved

 * More metadata is now preserved via labels. We may choose to
   reorganize or eliminate some of these labels in time but it's easier
   to remove metadata after import than it is to reintroduce it. The
   logic which maps Trac metadata to GitLab labels can be found here [2]

 * We now generate a Wiki table of contents [3] which is significantly
   more readable than GitLab's default page list. This will be updated
   by a cron job until underlying GitLab pages list becomes more
   readable.

 * We now generate redirects for Trac ticket and Wiki links (although
   this isn't visible in the staging instance)

 * Milestones are now properly closed when closed in Trac

 * Mapping between Trac and GitLab usernames is now a bit more robust

As in previous test imports, we would appreciate it if you could have a
look over the import and let us know of any problems your encounter.

If no serious issues are identified with the staging site we plan to
proceed with the migration this coming weekend. The current migration
plan is to perform the final import on gitlab.haskell.org on Saturday, 9
March 2019.

This will involve both gitlab.haskell.org and ghc.haskell.org being down
for likely the entirety of the day Saturday and likely some of Sunday
(EST time zone). Read-only access will be available to
gitlab.staging.haskell.org for ticket lookup while the import is
underway.

After the import we will wait at least a week or so before we begin the
process of decommissioning Trac, which will be kept in read-only mode
for the duration.

Do let me know if the 9 March timing is problematic.

Cheers,

- Ben


[1] https://gitlab.staging.haskell.org/ghc/ghc
[2] https://github.com/bgamari/trac-to-remarkup/blob/master/TicketImport.hs#L227
[3] https://gitlab.staging.haskell.org/ghc/ghc/wikis/index


signature.asc
Description: PGP signature
___
ghc-devs mailing list
ghc-devs@haskell.org
http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs


Re: [ANNOUNCE] GHC 8.6.4 is now available

2019-03-05 Thread Phyx
Thanks! To be fair I'm not really sure how popular it is. I was wondering
since once I upload the chocolatey packages it's immutable.

If there's anything I can help with let me know.

Cheers,
Tamar

On Tue, Mar 5, 2019, 21:47 Ben Gamari  wrote:

> Phyx  writes:
>
> > Hi Ben,
> >
> > Thanks for the release! I was wondering, any reason for the no i386
> Windows?
> > Should I just create the package without it or is it coming?
> >
> This is one configuration I haven't yet had a chance to CI-ify. I was
> hoping it would be missed but since you mention it I've gone ahead and
> put up an attempt at fixing this (!495 [1]). It will likely take a few
> iterations to get right but I'll try to get it sorted by the end of the
> week.
>
> Cheers,
>
> - Ben
>
>
> [1] https://gitlab.haskell.org/ghc/ghc/merge_requests/495
>
___
ghc-devs mailing list
ghc-devs@haskell.org
http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs


Re: Testing GHC against Hackage via CI

2019-03-05 Thread Ben Gamari
Richard Eisenberg  writes:

> How will this affect workflow of developers submitting patches? For
> example, suppose I write a user-facing change that breaks some of
> these packages. Am I expected to patch up the breakage? How? Will the
> CI infrastructure detect this before merging or after?
>
> To be clear, I don't have specific answers I'm looking for here. In
> particular, I think it's reasonable to ask that the developer of a
> user-facing feature make sure that head.hackage works with the
> feature. This has the distinct advantage of making sure the developer
> knows that their patch breaks code and how it must be fixed. Indeed,
> this can all be fodder to force the developer to update the GHC
> migration guide alongside their work in fixing head.hackage. I just
> want to know what the steps are. :)
>
All very good questions. Frankly, many of them are still open. I should
have made this clearer:

The short answer is that in the short term very little is changing.
head.hackage is, at the moment, merely another tool that we can use to
evaluate contributions and identify regressions in the compiler; it's
not (yet) a requirement that MRs pass the job.

The reason is that I don't think we are yet in a position to start
requiring contributors to update head.hackage. For one, the workflow for
doing so is arguably not well enough documented (something that I will
be working to fix). Moreover, it's quite unclear to me exactly how much
work maintaining this infrastructure is going to require. I'd like to
better understand this before requiring that contributors put in the
work.

Cheers,

- Ben



signature.asc
Description: PGP signature
___
ghc-devs mailing list
ghc-devs@haskell.org
http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs


Re: [ANNOUNCE] GHC 8.6.4 is now available

2019-03-05 Thread Ben Gamari
Phyx  writes:

> Hi Ben,
>
> Thanks for the release! I was wondering, any reason for the no i386 Windows?
> Should I just create the package without it or is it coming?
>
This is one configuration I haven't yet had a chance to CI-ify. I was
hoping it would be missed but since you mention it I've gone ahead and
put up an attempt at fixing this (!495 [1]). It will likely take a few
iterations to get right but I'll try to get it sorted by the end of the
week.

Cheers,

- Ben


[1] https://gitlab.haskell.org/ghc/ghc/merge_requests/495


signature.asc
Description: PGP signature
___
ghc-devs mailing list
ghc-devs@haskell.org
http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs


Re: [ANNOUNCE] GHC 8.6.4 is now available

2019-03-05 Thread Phyx
Hi Ben,

Thanks for the release! I was wondering, any reason for the no i386 Windows?
Should I just create the package without it or is it coming?

Thanks,
Tamar

On Tue, Mar 5, 2019 at 8:53 PM Ben Gamari  wrote:

>
> Hello everyone,
>
> The GHC team is very happy to announce the availability of GHC 8.6.4, a
> bugfix release in the GHC 8.6 series. The source distribution, binary
> distributions, and documentation for this release are available at
>
> https://downloads.haskell.org/~ghc/8.6.4
>
> The 8.6.4 release fixes several regressions present in 8.6.3 including:
>
>  - A regression resulting in segmentation faults on Windows introduced
>by the fix for #16071 backported in 8.6.3. This fix has been reverted,
>meaning that 8.6.4 is once again susceptible to #16071. #16071 will
>be fixed in GHC 8.8.1.
>
>  - A bug resulting in incorrect locking on Darwin, potentially resulting
>in hangs at shutdown (#16150)
>
>  - A few bugs in the profiled runtime resulting in the potential for
>memory unsafety has been fixed (#15508).
>
>  - The `process` and `transformers` libraries shipped now properly
>reflect released Hackage releases (#16199)
>
>  - A bug where TH name resolution would break in a plugin context has
>been fixed (#16104)
>
>  - Compilers that do not support TemplateHaskell no longer advertise
>such support in `--supported-languages` (#16331)
>
> As a few of these issues are rather serious users are strongly
> encouraged to upgrade. See Trac [1] for a full list of issues resolved
> in this release.
>
> Note that this release ships with one significant but long-standing bug
> (#14251): Calls to functions taking both Float# and Double# may result
> in incorrect code generation when compiled using the LLVM code generator.
> This is not a new issue, it has existed as long as the LLVM code
> generator has existed; however, changes in code generation in 8.6 made
> it more likely that user code using only lifted types will trigger it.
>
> Note also that this is the first release cut from our (yet again)
> revamped continuous integration infrastructure. While we have done a
> great deal of checking to ensure that the build configuration reflects
> that of previous releases, do let us know if something looks off.
>
> Happy compiling!
>
> Cheers,
>
> - Ben
>
> [1]
> https://ghc.haskell.org/trac/ghc/query?status=closed=8.6.4=id=summary=status=type=priority=milestone=component=priority
> ___
> ghc-devs mailing list
> ghc-devs@haskell.org
> http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs
>
___
ghc-devs mailing list
ghc-devs@haskell.org
http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs


Re: Testing GHC against Hackage via CI

2019-03-05 Thread Richard Eisenberg
How will this affect workflow of developers submitting patches? For example, 
suppose I write a user-facing change that breaks some of these packages. Am I 
expected to patch up the breakage? How? Will the CI infrastructure detect this 
before merging or after?

To be clear, I don't have specific answers I'm looking for here. In particular, 
I think it's reasonable to ask that the developer of a user-facing feature make 
sure that head.hackage works with the feature. This has the distinct advantage 
of making sure the developer knows that their patch breaks code and how it must 
be fixed. Indeed, this can all be fodder to force the developer to update the 
GHC migration guide alongside their work in fixing head.hackage. I just want to 
know what the steps are. :)

Thanks,
Richard

PS: And thanks, generally, to all of you doing the heavy lifting to get this 
infrastructure in place. This is all quite wonderful, even if there have been 
some bumps in the road en route!

> On Mar 5, 2019, at 1:10 PM, Ben Gamari  wrote:
> 
> Hello everyone,
> 
> As many of you know, recently I have been working on bringing up
> infrastructure for using CI-produced binary distributions to build a
> subset of Hackage using the head.hackage patchset.
> 
> Happily, this effort has now converged on a usable result, embodied in
> two merge requests:
> 
> * https://gitlab.haskell.org/ghc/head.hackage/merge_requests/2
> * https://gitlab.haskell.org/ghc/ghc/merge_requests/465
> 
> ghc/head.hackage!2 adds CI support to head.hackage. In addition to the
> usual pass/fail status, this job produces (e.g. [1]) a few additional
> products:
> 
> * a JSON summary of the run, describing the dependency graph and
>   pass/fail state of each package. we can feed to an external service to
>   track newly-failing packages.
> 
> * a (rendered) graphviz graph showing the dependency structure of the
>   built packages, each node colored by its pass/fail state
> 
> * a tarball of build logs, each including statistics from
>   -ddump-timings. The hope here is that we can use this to track
>   compiler performance on real-world code
> 
> ghc/ghc!465 adds a job to GHC's own CI pipeline to trigger a
> head.hackage job using the binary distribution produced earlier in the
> pipeline. This job will run automatically under a variety of
> circumstances:
> 
> * via the scheduled nightly pipeline
> 
> * on merge requests labelled with the `user-facing` label
> 
> * when manually started using a button on the MR's Pipelines tab
> 
> Currently the head.hackage MR tests only a small number of Hackage
> packages (and their dependencies). Specifically, we currently build
> `aeson`, `criterion`, `singletons`, `servant`, and `scotty`. This pulls
> in 127 packages in total.
> 
> There are a few things that remain to be done:
> 
> * Better document the existence of the job and how it is triggered
> 
> * Document how to update the list of tested packages
> 
> * Work out how to handle tracking of persistent breakage (e.g. we want
>   a notification when a package initially breaks but not in later
>   builds)
> 
> * Automatically push patched packages to a Hackage repository (e.g.
>   head.hackage.org) as a result of CI.
> 
> Cheers,
> 
> - Ben
> 
> 
> [1] https://gitlab.haskell.org/ghc/head.hackage/-/jobs/38022
> ___
> ghc-devs mailing list
> ghc-devs@haskell.org
> http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs

___
ghc-devs mailing list
ghc-devs@haskell.org
http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs


[ANNOUNCE] GHC 8.6.4 is now available

2019-03-05 Thread Ben Gamari

Hello everyone,

The GHC team is very happy to announce the availability of GHC 8.6.4, a
bugfix release in the GHC 8.6 series. The source distribution, binary
distributions, and documentation for this release are available at

https://downloads.haskell.org/~ghc/8.6.4

The 8.6.4 release fixes several regressions present in 8.6.3 including:

 - A regression resulting in segmentation faults on Windows introduced
   by the fix for #16071 backported in 8.6.3. This fix has been reverted,
   meaning that 8.6.4 is once again susceptible to #16071. #16071 will
   be fixed in GHC 8.8.1.

 - A bug resulting in incorrect locking on Darwin, potentially resulting
   in hangs at shutdown (#16150)

 - A few bugs in the profiled runtime resulting in the potential for
   memory unsafety has been fixed (#15508).

 - The `process` and `transformers` libraries shipped now properly
   reflect released Hackage releases (#16199)

 - A bug where TH name resolution would break in a plugin context has
   been fixed (#16104)

 - Compilers that do not support TemplateHaskell no longer advertise
   such support in `--supported-languages` (#16331)

As a few of these issues are rather serious users are strongly
encouraged to upgrade. See Trac [1] for a full list of issues resolved
in this release.

Note that this release ships with one significant but long-standing bug
(#14251): Calls to functions taking both Float# and Double# may result
in incorrect code generation when compiled using the LLVM code generator.
This is not a new issue, it has existed as long as the LLVM code
generator has existed; however, changes in code generation in 8.6 made
it more likely that user code using only lifted types will trigger it.

Note also that this is the first release cut from our (yet again)
revamped continuous integration infrastructure. While we have done a
great deal of checking to ensure that the build configuration reflects
that of previous releases, do let us know if something looks off.

Happy compiling!

Cheers,

- Ben

[1] 
https://ghc.haskell.org/trac/ghc/query?status=closed=8.6.4=id=summary=status=type=priority=milestone=component=priority
 


signature.asc
Description: PGP signature
___
ghc-devs mailing list
ghc-devs@haskell.org
http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs


Re: Testing GHC against Hackage via CI

2019-03-05 Thread Ben Gamari
Ryan Scott  writes:

> This is fantastic work! I'm looking forward to using this.
>
> Are there plans to merge GitLab's fork of head.hackage back into the
> upstream repo [1]? I ask since I regularly submit patches to upstream, but
> if the GitLab CI is using the fork, then it may take some time for upstream
> changes to make their way back to the fork.
>
Yes, if it's okay with Herbert I think this branch should be merged
upstream.

We might also consider going even further: making
gitlab.haskell.org/ghc/head.hackage the upstream repository. If we don't
do this I would likely need to maintain a "stable" branch alongside
`master` to ensure that the head.hackage build doesn't break due to bad
patches landing in `master`. Moving the upstream to GitLab would avoid
this since all patches landed would go through CI.

Cheers,

- Ben


signature.asc
Description: PGP signature
___
ghc-devs mailing list
ghc-devs@haskell.org
http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs


Re: Testing GHC against Hackage via CI

2019-03-05 Thread Ryan Scott
This is fantastic work! I'm looking forward to using this.

Are there plans to merge GitLab's fork of head.hackage back into the
upstream repo [1]? I ask since I regularly submit patches to upstream, but
if the GitLab CI is using the fork, then it may take some time for upstream
changes to make their way back to the fork.

Ryan S.
-
[1] https://github.com/hvr/head.hackage
___
ghc-devs mailing list
ghc-devs@haskell.org
http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs


Testing GHC against Hackage via CI

2019-03-05 Thread Ben Gamari
Hello everyone,

As many of you know, recently I have been working on bringing up
infrastructure for using CI-produced binary distributions to build a
subset of Hackage using the head.hackage patchset.

Happily, this effort has now converged on a usable result, embodied in
two merge requests:

 * https://gitlab.haskell.org/ghc/head.hackage/merge_requests/2
 * https://gitlab.haskell.org/ghc/ghc/merge_requests/465

ghc/head.hackage!2 adds CI support to head.hackage. In addition to the
usual pass/fail status, this job produces (e.g. [1]) a few additional
products:

 * a JSON summary of the run, describing the dependency graph and
   pass/fail state of each package. we can feed to an external service to
   track newly-failing packages.

 * a (rendered) graphviz graph showing the dependency structure of the
   built packages, each node colored by its pass/fail state

 * a tarball of build logs, each including statistics from
   -ddump-timings. The hope here is that we can use this to track
   compiler performance on real-world code

ghc/ghc!465 adds a job to GHC's own CI pipeline to trigger a
head.hackage job using the binary distribution produced earlier in the
pipeline. This job will run automatically under a variety of
circumstances:

 * via the scheduled nightly pipeline

 * on merge requests labelled with the `user-facing` label

 * when manually started using a button on the MR's Pipelines tab

Currently the head.hackage MR tests only a small number of Hackage
packages (and their dependencies). Specifically, we currently build
`aeson`, `criterion`, `singletons`, `servant`, and `scotty`. This pulls
in 127 packages in total.

There are a few things that remain to be done:

 * Better document the existence of the job and how it is triggered

 * Document how to update the list of tested packages

 * Work out how to handle tracking of persistent breakage (e.g. we want
   a notification when a package initially breaks but not in later
   builds)

 * Automatically push patched packages to a Hackage repository (e.g.
   head.hackage.org) as a result of CI.

Cheers,

- Ben


[1] https://gitlab.haskell.org/ghc/head.hackage/-/jobs/38022


signature.asc
Description: PGP signature
___
ghc-devs mailing list
ghc-devs@haskell.org
http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs


Re: Newcomers' Guide to GHC Development

2019-03-05 Thread Tobias Dammers
Hi, thanks for your feedback.

I'll get into some detail below.

On Sat, Mar 02, 2019 at 11:36:06AM +1100, Julian Leviston wrote:

> The updated version could be improved by shaping it into clearer
> sections because we’d like newcomers to feel like it’s light and easy.
> Layers is a great way to achieve this.
> 
> The first time I ran through the task list (not very long ago), it
> felt light and easy. This was because it was chunked well.
> 
> So, my suggestion would be to have a third sentence/paragraph in the
> introduction section that explains what the overall steps are that
> we’re going to explain next. Provide links down into those sections,
> and make it really clear that those sections are sections, if
> possible.

I like the idea of a short outline of the overall progression in the
introduction, so just added that. I won't add those links yet, because
due to the way this works in Gitlab, it's best to do it after the
document has solidified, because adding or removing headers (of any
level) will change the headers' generated ID properties, potentially
breaking any links.

As far as the chunking goes, I believe we already have a fairly decent
structure in place. The GitHub layout may not make it very obvious
though, and I think it'll be clearer on Gitlab. I did rearrange things a
tiny bit in order to fit in better with the overall arch though.

If you have concrete suggestions on how to improve the structure
further, please feel free to tell, or better yet, issue a PR on GitHub.

> At each section, you could reiterate how to do that driving from the
> overarching aim of the explanation for the section. (Having an
> introduction to each section would help here, too).

This seems like overkill to me. We need to strike a balance between
completeness and brevity, and we're bordering on "too long" already. I
did try to come up with suitable introductions, but they all ended being
paraphrasings of the title or the entire section, so I decided against
them.

Note that my goal here is to remove obstacles and friction, not to
persuade people into contributing - by the time you read this guide, you
should have been persuaded already.

Quoting the very first sentence in the guide:

| This page is intended to serve as the first stop for those people who
| say, "I want to contribute to GHC, but I don't know quite where to
| begin."


> For example, having a canonical way to determine what a good issue or
> feature to start on would be awesome, as would having somewhat of a
> mentor/buddy to help new users when working on their bugs (ie one or
> two people assigned to a newcomers’ first two or so tickets to help
> them through any issues until they feel confident). Not sure if our
> contributors allow for such things yet, tho.

I agree that that would be awesome; however, we have limited resources
at our disposal that we need to juggle between several concerns, and
mentoring newcomers is only one of them.

What we can offer right now is:

- Issues labeled "newcomers" (the guide already mentions these)
- Ad-hoc, no-strings-attached support from core GHC contributors and
  various volunteers via this mailing list and IRC (the guide mentions
  these, too)
- Some time from core contributors, as available, allocated to handling
  incoming issues and merge requests. We strive to provide feedback on
  every one of them, but we cannot make any hard promises as to the
  timeframe, and we have to prioritize.

On top of that, many individuals and third-party organisations run
various forms of mentoring, tutoring, guidance, hackathon events,
counseling, etc. Listing those would go way beyond the scope of this
document, but you should have little trouble getting suggestions via our
various communication channels.

Hope that clarifies things, and again, thanks a lot for your input.
___
ghc-devs mailing list
ghc-devs@haskell.org
http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs