Difference between revisions of "Hackage wiki page per project discussion"

From HaskellWiki
Jump to: navigation, search
(add my comments)
Line 1: Line 1:
 
== Purpose of this page ? ==
 
== Purpose of this page ? ==
 
collect thoughts about whether we should provide a wiki page (and maybe even more advanced features such as bug trackers) for all projects hosted on hackage
 
collect thoughts about whether we should provide a wiki page (and maybe even more advanced features such as bug trackers) for all projects hosted on hackage
  +
 
I'll post a link to this page to haskell-cafe so everyone should participate
 
I'll post a link to this page to haskell-cafe so everyone should participate
   
Line 10: Line 11:
 
Duncan Coutts proposed contacting the maintainer. If you don't receive replies within a time frame write to the haskell-cafe mailinglist. If you can't find him become the new maintainer.
 
Duncan Coutts proposed contacting the maintainer. If you don't receive replies within a time frame write to the haskell-cafe mailinglist. If you can't find him become the new maintainer.
   
While contacting the maintainer works very well within 3 days in most cases there are situations where maintainers reply they are on holidy ol got very busy lately.. In these cases I'd like to put my patch somewhere so that others can find it.
+
While contacting the maintainer works very well within 3 days in most cases there are situations where maintainers can't reply because they are on holiday or got very busy.. In these cases I'd like to put my patch somewhere so that others can find them.
   
Typically a bug tracker is used for this.
+
== What could a wiki page be used for? ==
   
hackage is the best index of all haskell packages we have
 
So everyone will look on hackage first.
 
   
Even if the maintainer replies within 3 days it doesn't make sense to upload a new version of a package for each patch.
 
  +
a) patches (which are removed when maintainers integrate them upstream)
   
Having too many versions on hackage would blow up the index.tar.gz and maybe put much stress on tools like cabal install.
 
  +
b) Howtos and pitfalls (written by users or maintainers)
   
That's why I proposed to Duncan today that we could just create a new link to the wiki for each project below the link to the package contents (cabal file)
 
  +
c) references to similar projects pointing out differences.
   
It would look like this:
 
  +
d) a smart lazy changelog. If a user hits a change he can add this to the
  +
wiki so that others can find out faster which version constraints to
  +
add to their .cabal file.
   
http://mawercer.de/~marc/hackage-link-example.jpg
 
  +
This looks like this:
  +
2.20: renamed foo to bar.
   
Thoughts:
 
  +
2.48: type change of iwillneverChange :: Int to Maybe Int
   
* package maintainers have to look at the wiki as well (do they?)
 
  +
e) a list of changes which will go into the next release of a package.
However they can be notified automatically when a page changes
 
  +
This may help you figuring out whether you should download the darcs repository.
   
* everyone can upload examples how to use a package
 
  +
f) many other ideas I can't think about yet.
   
* it's easier to provide important information such as:
 
  +
...
   
"This package is superseded by XY because: ..."
 
   
** We already have a mechanism to deprecate packages or to mark them as superseded. --[[User:DuncanCoutts|DuncanCoutts]] 00:25, 12 December 2009 (UTC)
 
  +
== implementation details: ==
   
Or hints such as: If you're interested in this package also read about ...
 
  +
design could look like this:
  +
http://mawercer.de/~marc/hackage-link-example.jpg
   
Or: Have a look at the darcs repostory. It cantains many bug fixes which will b released soon.
 
  +
The link would point to the haskell wiki having the url suffix /project-name.
   
* You don't have to create a web page for your (maybe small) project
 
  +
== When a wiki page can replace a .cabal file update ==
   
* You can discuss features and the roadmap of projects easily.
 
  +
* minor dependency changes
   
* Maintainers can be maintainers while others can still put their ideas or experiences online.
 
  +
* tell users about experimental branches
   
* should maintainers have a chance to disable this link?
 
  +
* it's easier to provide important information such as:
(Don't think so. Because this is the main feature that everybody can always put comments)
 
  +
  +
"This package is superseded by XY because: ..."
  +
  +
** We already have a mechanism to deprecate packages or to mark them as superseded. --[[User:DuncanCoutts|DuncanCoutts]] 00:25, 12 December 2009 (UTC)
  +
  +
[[User:MarcWeber|Marc Weber]]: Can you explain how this works or point me to the documentation?
   
 
The main point about this wiki idea is that you can attach arbitrary information and you don't have to wait for anyone to do so.
 
The main point about this wiki idea is that you can attach arbitrary information and you don't have to wait for anyone to do so.
Line 73: Line 80:
   
 
There is no problem with such a feature being opt-in, but whether it is something we require and impose on package authors needs much more of a social consensus before we go ahead.
 
There is no problem with such a feature being opt-in, but whether it is something we require and impose on package authors needs much more of a social consensus before we go ahead.
  +
  +
Reply [[User:MarcWeber|Marc Weber]]: Everybody knows that it is wiki content and will take care.
  +
  +
About effort: Note that package authors can watch their wiki pages easily.
  +
Authors and maintainers already do the hard work. Watching a wiki page is not mach work compared to writing a library. But they may find wiki contents of foreign projects that useful that they provide some contents their selves
  +
  +
== wiki alternatives ==
  +
If content isn't put on a wiki what do people do instead?
  +
* They may do nothing (bad)
  +
* They may write a blog (bad because others don't find it or because content gets out of date). Which way is more likely providing you with valuable information: A blog found by google or an attached wiki page people can keep up to date?
  +
* They may write to the mailinglist. Things are archived forever. On the wiki they are as well but not only a small amount of visitors ever looks at the history of a page..
  +
  +
== feedback ==
  +
  +
I don't mind:
  +
* marco-oweber@gmx.de (Marc Weber)
  +
  +
I do mind:
  +
*
  +
  +
I don't care:
  +
*
  +
  +
I won't tell you:
  +
*
  +
  +
== Notes ==
  +
You can watch this page

Revision as of 23:46, 12 December 2009

Purpose of this page ?

collect thoughts about whether we should provide a wiki page (and maybe even more advanced features such as bug trackers) for all projects hosted on hackage

I'll post a link to this page to haskell-cafe so everyone should participate

Why a Wiki

We do have about 1500 packages on hackage. Hackage was made live easier. While packaging some packages for nix (using Hack-Nix) I had to write some patches.

If you have a patch what to do? Duncan Coutts proposed contacting the maintainer. If you don't receive replies within a time frame write to the haskell-cafe mailinglist. If you can't find him become the new maintainer.

While contacting the maintainer works very well within 3 days in most cases there are situations where maintainers can't reply because they are on holiday or got very busy.. In these cases I'd like to put my patch somewhere so that others can find them.

What could a wiki page be used for?

a) patches (which are removed when maintainers integrate them upstream)

b) Howtos and pitfalls (written by users or maintainers)

c) references to similar projects pointing out differences.

d) a smart lazy changelog. If a user hits a change he can add this to the

 wiki so that others can find out faster which version constraints to
 add to their .cabal file.
 This looks like this:
 2.20: renamed foo to bar.
 2.48: type change of iwillneverChange :: Int  to  Maybe Int

e) a list of changes which will go into the next release of a package.

  This may help you figuring out whether you should download the darcs repository.

f) many other ideas I can't think about yet.

...


implementation details:

design could look like this:

 hackage-link-example.jpg

The link would point to the haskell wiki having the url suffix /project-name.

When a wiki page can replace a .cabal file update

  • minor dependency changes
  • tell users about experimental branches
  • it's easier to provide important information such as:
 "This package is superseded by XY because: ..."
    • We already have a mechanism to deprecate packages or to mark them as superseded. --DuncanCoutts 00:25, 12 December 2009 (UTC)

Marc Weber: Can you explain how this works or point me to the documentation?

The main point about this wiki idea is that you can attach arbitrary information and you don't have to wait for anyone to do so. Get things done. Provide patches. Link them on the wiki. Come back later and discuss your proposals with the maintainer. Keep summaries of discussions on subjects accesible by everyone. ...

Of course I know that the maintainers are the people doing the real work. But look at it from a different view: Having such a forum for all projects by default also means that a maintainer can let others do some of the work knowing that they don't have to reply within some days.

The wiki can host all information which may be useful but which wasn't foreseen by hackage or cabal devs. We must keep agile and move forward only.

You may rewrite this arcticle from scratch. Just add your thoughts and ideas and how you like this idea.

Concerns

My (DuncanCoutts) concern is about the consent from package authors. Hackage is a social bargain. We ask package authors to distribute their work through hackage because it provides benefits to the community. If we impose too much on package authors then they may decide it's just not worth it.

In particular, if we automatically create a wiki page for every package then we are imposing additional obligations on package authors. As a package author I might be concerned that this wiki page duplicates an existing home page or bug tracking system. If there's a wiki page about my project then I am effectively obligated to check it from time to time, since users will inevitably report bugs etc there. It is that extra obligation that package authors may resent.

There is no problem with such a feature being opt-in, but whether it is something we require and impose on package authors needs much more of a social consensus before we go ahead.

Reply Marc Weber: Everybody knows that it is wiki content and will take care.

About effort: Note that package authors can watch their wiki pages easily. Authors and maintainers already do the hard work. Watching a wiki page is not mach work compared to writing a library. But they may find wiki contents of foreign projects that useful that they provide some contents their selves

wiki alternatives

If content isn't put on a wiki what do people do instead?

  • They may do nothing (bad)
  • They may write a blog (bad because others don't find it or because content gets out of date). Which way is more likely providing you with valuable information: A blog found by google or an attached wiki page people can keep up to date?
  • They may write to the mailinglist. Things are archived forever. On the wiki they are as well but not only a small amount of visitors ever looks at the history of a page..

feedback

I don't mind:

  • marco-oweber@gmx.de (Marc Weber)

I do mind:

I don't care:

I won't tell you:

Notes

You can watch this page