Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Loading…

Want to help? #110

Closed
gelisam opened this Issue · 13 comments

3 participants

@gelisam
Owner

For the benefit of eventual contributors who want to work on this project, I am labelling some of the open issues as easy, medium and hard.

Of course, all issues will be somewhat hard if you're not familar with the codebase. Feel free to ask questions!

easy means you should be able to find a solution just by finding the appropriate place in the code (presumably with my help or melrief's) and making a small local change.

medium issues will require you to link a few pieces together, either by getting familiar with an outside library, an unusual Haskell feature, or some other part of Hawk's codebase.

hard issues may require the code to be refactored in order to create a place where the new feature can be added. I would prefer if the refactoring and the addition of the feature were added separately.

Issues with no milestone (except this one) have not yet been classified into a difficulty level, and probably haven't even yet been approved as a feature we might want to add to Hawk.

Issues with a milestone but with no difficulty markers should not be attempted, because we don't yet know how we want to proceed or because it would be better to wait until after a pending refactoring.

@gelisam
Owner

Here is a quick tour of the codebase, as of af23459.

First, parseArgs converts the command-line arguments into a HawkSpec, a precise type describing the valid commands which can be passed to the hawk executable.

Then, processSpec executes this HawkSpec, most commonly by caching the user prelude, and by asking the hint library to interpret the user expression.

At this point it is the Hawk runtime which takes over, using processTable to interpret standard input as a delimiter-separated table and to manipulate it via the user expression. Depending on the type of the user expression, an appropriate output format is then chosen and sent to standard output.

@gelisam
Owner

At the moment, the easiest open task is probably to add a unit test for NoImplicitPrelude, the most interesting open task is probably to prevent type errors while manipulating strings representing Haskell code, while the most important open task is probably compatibility with ghc 7.8.

@melrief
Collaborator

Nice description of the codebase, you could copy it inside the documentation page calling it "Contribute to the code".

@gelisam
Owner
@shaleh

Perhaps putting a CONTRIBUTING file that also has a link to docs/code-overview.md would work?

@shaleh

BTW the thing that consistently tripped me up during my Text patch was that runtime/* is outside of src/*. With lots of similar System/Console/blah/blah paths it was easy to get turned around. Including a quick code layout along with your code overview might help the next contributor out.

@melrief
Collaborator

Creating a technical documentation could be an idea to help new people getting involved. We changed the code a lot between the past two major releases and thus making such a documentation wasn't a good idea. Now that the code is more stable, we should consider writing a few guidelines. As soon as I have some free time (apparently before July), I think we will set the features of the 1.2 version of Hawk and this time we will include also the documentation. There is also a tutorial to complete and other documentation for users. More in general, there is a lot of documentation to create to help new users and developers.

@gelisam
Owner

Perhaps putting a CONTRIBUTING file that also has a link to docs/code-overview.md would work?

Okay, I'll take a stab at writing this.

@gelisam
Owner

Here is my first stab. I'm haven't mentioned doc/code-overview.md yet, because that doesn't exist yet.

@gelisam
Owner

I have been writing doc/code-overview.md, and it's taking a lot longer than expected. The document itself is also longer than I would have thought. Almost done, I'll submit it soon!

@gelisam
Owner

All right, here it is!

@shaleh, since you have only become familiar with the codebase very recently, you are in the best position to determine whether this document is actually useful. Do you think this kind of document would have helped you learn the code base more quickly? More completely? Is it too long? Are the explanations detailed enough? Are they clear? Any feedback would help.

@shaleh

The explanation of why and the thinking behind it is very welcomed. There were various pieces of runtime I had not worked out.

Not too long. You could always come back and add a more detailed document later.

@gelisam
Owner

Great! In that case, I'll merge the change into master and close this issue.

@gelisam gelisam closed this in 122345c
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Something went wrong with that request. Please try again.