Want to help? #110

Closed
gelisam opened this Issue Apr 4, 2014 · 13 comments

Comments

Projects
None yet
3 participants
Owner

gelisam commented Apr 4, 2014

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.

Owner

gelisam commented Apr 4, 2014

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.

Owner

gelisam commented Apr 4, 2014

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.

Collaborator

melrief commented Apr 4, 2014

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

Owner

gelisam commented Apr 4, 2014

Or maybe in the file CONTRIBUTING, which github treats specially [1]?
Except that file is supposed to contain rules for acceptable patches, which
is not quite what we're writing here...

[1] https://github.com/blog/1184-contributing-guidelines
On 4 Apr 2014 05:53, "Mario Pastorelli" notifications@github.com wrote:

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


Reply to this email directly or view it on GitHubhttps://github.com/gelisam/hawk/issues/110#issuecomment-39548532
.

shaleh commented Jun 5, 2014

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

shaleh commented Jun 5, 2014

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.

Collaborator

melrief commented Jun 5, 2014

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.

Owner

gelisam commented Jun 7, 2014

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.

Owner

gelisam commented Jun 7, 2014

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

Owner

gelisam commented Jun 11, 2014

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!

Owner

gelisam commented Jun 11, 2014

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 commented Jun 13, 2014

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.

Owner

gelisam commented Jun 13, 2014

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

@gelisam gelisam closed this in 122345c Jun 13, 2014

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment