Hacking Gitit... advice for newbies

[John Maxwell]

I've been using Gitit for some months now, enough to know that this is a nearly perfect blend of features and design choices. 

The only problem is that it's Haskell... and I'm utterly lost with it. I want to hack it, but I'm frankly stymied... for a long while I kept hoping I'd find something just like it except written in Python. But I accept now that this isn't real. Gitit is in Haskell and I'm going to have to make peace with it.

I want to hack the template system... not just how it looks (I've gone a fair ways with that already)... I want to change the functionality: filter things based on categories, count backlinks, build a tag cloud based on categories... that sort of thing. Not wholesale changes, but deeper customizations than the templates offer currently.

Can anyone here give me some practical advice on how to effectively get started with this? Learning Haskell syntax is only a beginning... Gitit is built on top of a whole pile of other components and platforms, and there is an idiom quite different from what I'm used to. So, if you were to advise somebody who is familiar with Python or Ruby, how to begin making changes to the way GitIt does things, where to start? Any good tutorials, or even advice on what to avoid?

A pointer or two would be very much appreciated. 

Thanks!

John Maxwell

Simon Fraser University

Vancouver, BC

jmax @ sfu.ca

[John MacFarlane]

Why don't you describe fairly precisely one change you'd like
to make. Then maybe I or someone else can point you to the right
place in the code.

+++ John Maxwell [Mar 11 13 18:17 ]:

> --
> You received this message because you are subscribed to the Google
> Groups "gitit-discuss" group.
> To unsubscribe from this group and stop receiving emails from it, send
> an email to gitit-discus...@googlegroups.com.
> To post to this group, send email to gitit-...@googlegroups.com.
> Visit this group at
> [1]http://groups.google.com/group/gitit-discuss?hl=en.
> For more options, visit [2]https://groups.google.com/groups/opt_out.
>
> References
>
> 1. http://groups.google.com/group/gitit-discuss?hl=en
> 2. https://groups.google.com/groups/opt_out

[Henning Thielemann]

On Mon, 11 Mar 2013, John MacFarlane wrote:

> Why don't you describe fairly precisely one change you'd like
> to make. Then maybe I or someone else can point you to the right
> place in the code.

Btw. has someone inspected my patches for extended filtering by categories
and sub-directories?

http://code.haskell.org/~thielema/gitit/

[Henning Thielemann]

On Mon, 11 Mar 2013, John Maxwell wrote:

> I've been using Gitit for some months now, enough to know that this is a nearly perfect blend of features

> and design choices.ￜ

> The only problem is that it's Haskell... and I'm utterly lost with it. I want to hack it, but I'm frankly
> stymied... for a long while I kept hoping I'd find something just like it except written in Python. But I
> accept now that this isn't real. Gitit is in Haskell and I'm going to have to make peace with it.

I think there are good news and bad news. Good news: Haskell is a very
elegant and safe language and it is definitely worth learning. If you are
used to Python then you are certainly already familiar with some of its
functional features like lambda expressions and the Yield statement. The
bad news are: Even if you used a functional programming style in a
language like Python, Haskell is still quite different and it needs time
to learn it. Even if you manage to add some feature to gitit I guess you
still need someone to turn that code into idiomatic Haskell code.

> Can anyone here give me some practical advice on how to effectively get
> started with this? Learning Haskell syntax is only a beginning...

I think the Haskell syntax requires the least effort when learning
Haskell. Much more effort goes into understanding the functional paradigm
and the type system. If you want to quickly learn Haskell for applications
like gitit then the book "Real World Haskell" might help you.

> Gitit is built on top of a whole pile of other components and platforms, and
> there is an idiom quite different from what I'm used to. So, if you were to advise somebody who is familiar
> with Python or Ruby, how to begin making changes to the way GitIt does things, where to start? Any good
> tutorials, or even advice on what to avoid?

Maybe those Wiki articles and categories can help you:

http://www.haskell.org/haskellwiki/Haskell_programming_tips
http://www.haskell.org/haskellwiki/Category:Style
http://www.haskell.org/haskellwiki/Category:Syntax
http://www.haskell.org/haskellwiki/Category:Idioms
http://www.haskell.org/haskellwiki/Category:FAQ

[John Maxwell]

google...@henning-thielemann.de wrote:

 

I think there are good news and bad news...

Thanks very much for these pointers... I'll spend some time with it and see how it goes.

Cheers!

- JMax 

[John MacFarlane]

+++ Henning Thielemann [Mar 12 13 11:03 ]:

Can you generate a patch on top of the latest gitit from github?

[Henning Thielemann]

On Tue, 12 Mar 2013, John MacFarlane wrote:

> +++ Henning Thielemann [Mar 12 13 11:03 ]:
>>

>> http://code.haskell.org/~thielema/gitit/
>
> Can you generate a patch on top of the latest gitit from github?

What do you mean precisely? Shall I merge the latest commits from github
into my fork or do you want a patch generated by git-diff?

[John MacFarlane]

PS. You might also check out

https://github.com/jgm/gitit2

which reimplements gitit using the Yesod web framework in about
1/3 the lines of code. There are some features still missing,
but it is a much cleaner code base and probably easier to understand
and hack.

Still missing:

* preview in edit
* many config options
* plugins (some of the code is finished)
* site initialization
* user accounts/login

+++ John Maxwell [Mar 11 13 18:17 ]:

[Henning Thielemann]

On Tue, 12 Mar 2013, John MacFarlane wrote:

> PS. You might also check out
>
> https://github.com/jgm/gitit2
>
> which reimplements gitit using the Yesod web framework in about
> 1/3 the lines of code. There are some features still missing,
> but it is a much cleaner code base and probably easier to understand
> and hack.

Why is it shorter? Because of missing features? Because Yesod allows for
shorter code than Happstack? Can you give me an idea of the advantages of
one framework over the other?

[John MacFarlane]

+++ Henning Thielemann [Mar 12 13 23:38 ]:

Partly because of missing features. But mostly because (a) Yesod
allows for shorter code, (b) I knew Haskell better in the rewrite,
(b) gitit was written in the olden days of Happstack, back when it
was called HAppS, so it had to solve some problems in ugly ways that
are now done much more elegantly.

I think that the code will remain much shorter and cleaner even
after the few remaining features are added (assuming it ever
happens).

I've just updated the gitit2 repository so that it builds with
the latest yesod and pandoc -- it should be cabal installable,
or at least cabal-dev installable... If you want to play with
it, be aware that it doesn't create the wikidata directory,
so just copy an existing gitit wikidata directory. Settings are
in config/settings.yaml.

John

[John Maxwell]

On Monday, March 11, 2013 8:44:10 PM UTC-7, fiddlosopher wrote:

 

Why don't you describe fairly precisely one change you'd like
to make.  Then maybe I or someone else can point you to the right
place in the code.

OK, for instance: I'd like to take the functionality shown in "Recent Activity" (_activity), 

  - modify it so that the links point to the regular page view rather than a particular revision, 

  - limit the number of results it returns, 

  - and wrap that up as a template chunk so that I could easily add it to the page sidebar or header.

The first two things look solveable by trial-and-error, as I can see the showActivity handler in Handlers.hs. But I'm not at all sure how (or if) this could be callable from within a template. 

Any advice or insight?

[John MacFarlane]

+++ John Maxwell [Mar 14 13 11:35 ]:

I would create a route that serves up the HTML for the modified recent
activity, then add some javascript to the template to populate a div
with this on page load.

This is how we currently handle the logged in user information.

[John Maxwell]

On Thursday, March 14, 2013 3:00:43 PM UTC-7, fiddlosopher wrote: 

 

This is how we currently handle the logged in user information.

OK... that's good... I'l look at how that's done and see if I can follow that. Thanks! 

[Kẏra]

How would using the new happstack compare with yesod?

Also, have you considered applying to be part of Google Summer of Code and Gnome Outreach Project for Women?

[John MacFarlane]

+++ Kẏra [Jul 01 13 10:49 ]:

> How would using the new happstack compare with yesod?

I like the new happstack, and maybe I'd even prefer it in the end.
(I just wanted to try yesod, and I liked the "subsites.")

> Also, have you considered applying to be part of Google Summer of Code
> and Gnome Outreach Project for Women?

No, I really don't have much time for gitit these days.

[Kẏra]

On Mon, Jul 1, 2013 at 2:56 PM, John MacFarlane <fiddlo...@gmail.com> wrote:

+++ Kẏra [Jul 01 13 10:49 ]:

>    How would using the new happstack compare with yesod?

I like the new happstack, and maybe I'd even prefer it in the end.
(I just wanted to try yesod, and I liked the "subsites.")

Ah, but too late to switch back now, I suppose?
 

>    Also, have you considered applying to be part of Google Summer of Code
>    and Gnome Outreach Project for Women?

No, I really don't have much time for gitit these days.

Sad, but I understand. Hopefully others (maybe myself) could pick up the slack!

--

Board of Directors, Free Culture Foundation: www.freeculture.org

Web: kxra.info  -  StatusNet Microblog: http://identi.ca/kxra
Email: kx...@freeculture.org  -  SMS: +1.617.340.3661
Jabber/XMPP: kx...@riseup.net  -  IRC: kxra @freenode @oftc @indymedia

[John MacFarlane]

+++ Kẏra [Jul 01 13 15:00 ]:

> On Mon, Jul 1, 2013 at 2:56 PM, John MacFarlane
> <[1]fiddlo...@gmail.com> wrote:
>
> +++ Kẏra [Jul 01 13 10:49 ]:
>
> > How would using the new happstack compare with yesod?
>
> I like the new happstack, and maybe I'd even prefer it in the end.
> (I just wanted to try yesod, and I liked the "subsites.")
>
> Ah, but too late to switch back now, I suppose?

Not necessarily. If you wanted to learn Haskell web development,
rewriting gitit2 in modern happstack would teach you a lot.

[Kẏra]

--
You received this message because you are subscribed to the Google Groups "gitit-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to gitit-discus...@googlegroups.com.
To post to this group, send email to gitit-...@googlegroups.com.

Visit this group at http://groups.google.com/group/gitit-discuss.
For more options, visit https://groups.google.com/groups/opt_out

Cool! That might be fun. Would it be possible for very inexperienced haskell hackers?

Would it require a total rewrite, or just modifying the existing codebase?

On an unrelated note, is there a reason you don't choose AGPL (which was designed to protect web apps) instead of GPL?