http://mtov.github.io/Truck-Factor/
I have a feeling gambit would have a Truck-Factor of 0.5 (Marc wouldn’t need to be killed, just injured …)
Brad
Afficher les réponses par date
At least it is not 0!
Seriously, let me reiterate that I am open to having people contribute to Gambit. I think that is the best way to increase the truck-factor. It is of course a chicken and egg problem, but I feel there are more and more users that are working with and on Gambit, so maybe soon there will be enough momentum to keep the ball rolling on its own.
From my point of view, it is a heavy workload to be simultaneously:
- doing research on programming language implementation (related to Scheme of course) - implementing research ideas in Gambit so that they are robust and stable - engineering parts of the runtime system for good performance or to add practical features - maintaining the Gambit web site, Gambit mailing list and documentation - making prereleases - writing unit tests - advising students working on Gambit - helping out users having problems using Gambit (porting to new platforms, debugging their code, etc)
Don’t get me wrong… I love that kind of work, but there’s just so much I can do.
So if you or anyone else wants to help on any of those activities, please contact me! I would love it if the truck-factor was above 1!
Here are some ideas off the top of my head:
- documenting all Gambit features - writing unit tests for all those features - maintaining Gambit packages for all linux distributions - writing tutorials and use cases
Marc
On Jul 22, 2015, at 10:41 PM, Bradley Lucier lucier@math.purdue.edu wrote:
http://mtov.github.io/Truck-Factor/
I have a feeling gambit would have a Truck-Factor of 0.5 (Marc wouldn’t need to be killed, just injured …)
Brad
On 07/23/2015 10:52 AM, Marc Feeley wrote:
Here are some ideas off the top of my head:
- documenting all Gambit features
- writing unit tests for all those features
- maintaining Gambit packages for all linux distributions
- writing tutorials and use cases
Marc, I once had a summer job at the National Research Council on Montreal Road outside of Ottawa, where my supervisor told me to find something interesting to do; if I couldn't find something to do, then the default job was to flowchart his main application program.
Which I thought would be *boring*.
Those things you list are useful, but they sound *boring*, and they won't increase the truck factor at all.
In 1998 you proposed to me to rewrite the Gambit bignum code; to me, that wasn't boring, and I'm still thinking about it today. (Hell, I even used some new algorithms picked up from some research papers.)
Once Gambit has a module system of some kind, then people can begin to contribute the kind of libraries that Chicken and Racket have in spades.
Will the R7RS module system be sufficient for this purpose?
Making Gambit R7RS compliant would help things. Whoever does it will have to learn something of Gambit's internals, I'm sure it's interesting to *someone*, and it would increase the truck factor by at least a fraction.
There must be other projects that:
1. Require someone to learn something about Gambit's internals. 2. Have a specific goal to work towards. 3. Increases the truck factor. 4. Is interesting!
For example, if someone said "I have a big project about such-and-such and if Gambit only did <whatever> better" then, depending on what <whatever> is, it might be another good way for someone to get into Gambit internals and contribute something.
Brad
2015-07-23 20:05 GMT+02:00 Bradley Lucier lucier@math.purdue.edu:
On 07/23/2015 10:52 AM, Marc Feeley wrote:
Here are some ideas off the top of my head:
- documenting all Gambit features
- writing unit tests for all those features
- maintaining Gambit packages for all linux distributions
- writing tutorials and use cases
Marc, I once had a summer job at the National Research Council on Montreal Road outside of Ottawa, where my supervisor told me to find something interesting to do; if I couldn't find something to do, then the default job was to flowchart his main application program.
Which I thought would be *boring*.
Those things you list are useful, but they sound *boring*, and they won't increase the truck factor at all.
In 1998 you proposed to me to rewrite the Gambit bignum code; to me, that wasn't boring, and I'm still thinking about it today. (Hell, I even used some new algorithms picked up from some research papers.)
Once Gambit has a module system of some kind, then people can begin to contribute the kind of libraries that Chicken and Racket have in spades.
Will the R7RS module system be sufficient for this purpose?
Making Gambit R7RS compliant would help things. Whoever does it will have to learn something of Gambit's internals, I'm sure it's interesting to *someone*, and it would increase the truck factor by at least a fraction.
There must be other projects that:
- Require someone to learn something about Gambit's internals.
- Have a specific goal to work towards.
- Increases the truck factor.
- Is interesting!
For example, if someone said "I have a big project about such-and-such and if Gambit only did <whatever> better" then, depending on what <whatever> is, it might be another good way for someone to get into Gambit internals and contribute something.
Brad, Gambit's present sources are incredibly fun.
You don't need to add code for making increasing the "truck factor" realistic. Maybe adding comments and documentation though.
At ~200klocs, its sourcecode is short enough for people to be able to grasp it too so it's realistic - fantastic.
On 07/23/2015 02:53 PM, Adam wrote:
Brad, Gambit's present sources are incredibly fun.
I agree.
You don't need to add code for making increasing the "truck factor" realistic. Maybe adding comments and documentation though.
Yeah, that would be good. I should have mentioned it. People could start with with easier things like _std.scm before attempting to conquer _io.scm, for example.
At ~200klocs, its sourcecode is short enough for people to be able to grasp it too so it's realistic - fantastic.
It's 200kloc of macro-heavy, dense code. I agree, in many ways it is beautiful (especially the way Marc uses macros to avoid rewriting code), but it will require some study.
Brad
Adding the R7RS module system to Gambit would be great! Unfortunately, it requires a very good understanding of the Gambit internals (AST representation, parsing, environment representation in interpreter and compiler). So before tackling such a project a contributor needs to get a better overview of the whole system. That’s the point of (some of) the tasks I mentionned.
Documenting and writing unit tests for all the Gambit features requires looking through the source code, figuring out the function of a primitive, and testing it out (in essence writing basic unit tests). And it *does* increase the truck-factor because those doing this will have a better understanding of the system, and other people reading the docs will also have a better understanding of the system.
Another task (not on the previous list) achieving the same goal is a refactoring of the Gambit runtime system to use the “define-library” form (https://github.com/feeley/define-library) which is very close syntactically to the R7RS module system but lacks hygiene. This task would help clean up the source code of the runtime system (in particular it would get rid of many of the ## prefixes), it would expose the dependencies between the runtime system modules, and make the source code easier to read, understand and modify.
In fact, let me suggest you do this for _num.scm, since it is a big piece of code that’s not easy to understand and could benefit from the module system.
As for writing libraries for Gambit, that could be done with define-library in preparation of a fully R7RS compliant Gambit. Helping out with extensions to SchemeSpheres and LambdaNative would also be good indirect contributions to Gambit.
Marc
On Jul 23, 2015, at 2:05 PM, Bradley Lucier lucier@math.purdue.edu wrote:
On 07/23/2015 10:52 AM, Marc Feeley wrote:
Here are some ideas off the top of my head:
- documenting all Gambit features
- writing unit tests for all those features
- maintaining Gambit packages for all linux distributions
- writing tutorials and use cases
Marc, I once had a summer job at the National Research Council on Montreal Road outside of Ottawa, where my supervisor told me to find something interesting to do; if I couldn't find something to do, then the default job was to flowchart his main application program.
Which I thought would be *boring*.
Those things you list are useful, but they sound *boring*, and they won't increase the truck factor at all.
In 1998 you proposed to me to rewrite the Gambit bignum code; to me, that wasn't boring, and I'm still thinking about it today. (Hell, I even used some new algorithms picked up from some research papers.)
Once Gambit has a module system of some kind, then people can begin to contribute the kind of libraries that Chicken and Racket have in spades.
Will the R7RS module system be sufficient for this purpose?
Making Gambit R7RS compliant would help things. Whoever does it will have to learn something of Gambit's internals, I'm sure it's interesting to *someone*, and it would increase the truck factor by at least a fraction.
There must be other projects that:
- Require someone to learn something about Gambit's internals.
- Have a specific goal to work towards.
- Increases the truck factor.
- Is interesting!
For example, if someone said "I have a big project about such-and-such and if Gambit only did <whatever> better" then, depending on what <whatever> is, it might be another good way for someone to get into Gambit internals and contribute something.
Brad
On 07/23/2015 03:06 PM, Marc Feeley wrote:
Documenting and writing unit tests for all the Gambit features requires looking through the source code, figuring out the function of a primitive, and testing it out (in essence writing basic unit tests). And it *does* increase the truck-factor because those doing this will have a better understanding of the system, and other people reading the docs will also have a better understanding of the system.
OK. My feeling about this is that you're documenting interfaces, not the implementation, by doing this.
Another task (not on the previous list) achieving the same goal is a refactoring of the Gambit runtime system to use the “define-library” form (https://github.com/feeley/define-library) which is very close syntactically to the R7RS module system but lacks hygiene. This task would help clean up the source code of the runtime system (in particular it would get rid of many of the ## prefixes), it would expose the dependencies between the runtime system modules, and make the source code easier to read, understand and modify.
How does one use the "define-library" form? Is there documentation somewhere, or does one just guess from the examples in that git repository?
Helping out with extensions to SchemeSpheres and LambdaNative would also be good indirect contributions to Gambit.
I looked at LambdaNative a bit while I was laid up this spring, but in the end I didn't contribute anything. Perhaps one needs to be more familiar with development on small devices, or perhaps I had other deficiencies.
Brad
On Jul 23, 2015, at 3:24 PM, Bradley Lucier lucier@math.purdue.edu wrote:
How does one use the "define-library" form? Is there documentation somewhere, or does one just guess from the examples in that git repository?
Yes you can look at test.scm in that repository. There are also other repositories in my github account which show more advanced uses of define-library, for example
https://github.com/feeley/base64/blob/master/base64.scm
Marc
On Thu, Jul 23, 2015 at 10:54 PM, Marc Feeley feeley@iro.umontreal.ca wrote:
On Jul 23, 2015, at 3:24 PM, Bradley Lucier lucier@math.purdue.edu
wrote:
How does one use the "define-library" form? Is there documentation
somewhere, or does one just guess from the examples in that git repository?
I think the topic of this thread is very important indeed. I completely relate to Marc's position: there is only so much you can do. And eventually we all have to do something to make a living, which unfortunately for many of us is not 100% Gambit-related.
Also, SchemeSpheres is ready to use R7RS as soon as Gambit implements it. It sits a layer above that, and uses a custom version of psyntax and R7RS to get the minimal support to be functional and usable now.
Yeah a deep understanding of Gambit internal system would be really helpful when dealing with any macrology / module systems..
My last attempt was mostly an rewrite against riaxpander line by line in gambit and it's https://github.com/wsxiaoys/nova/blob/master/nova.scm mostly working (successfully loading chibi's init.scm and passed its r7rs test suite). While to produce more informative syntax mistake, it needs work to dive into gambit's source handling & internal symbols management..
Sadly have to do something to make a living after graduation :(
On Thu, Jul 23, 2015 at 2:40 PM, Álvaro Castro-Castilla < alvaro.castro.castilla@gmail.com> wrote:
On Thu, Jul 23, 2015 at 10:54 PM, Marc Feeley feeley@iro.umontreal.ca wrote:
On Jul 23, 2015, at 3:24 PM, Bradley Lucier lucier@math.purdue.edu
wrote:
How does one use the "define-library" form? Is there documentation
somewhere, or does one just guess from the examples in that git repository?
I think the topic of this thread is very important indeed. I completely relate to Marc's position: there is only so much you can do. And eventually we all have to do something to make a living, which unfortunately for many of us is not 100% Gambit-related.
Also, SchemeSpheres is ready to use R7RS as soon as Gambit implements it. It sits a layer above that, and uses a custom version of psyntax and R7RS to get the minimal support to be functional and usable now.
Gambit-list mailing list Gambit-list@iro.umontreal.ca https://webmail.iro.umontreal.ca/mailman/listinfo/gambit-list
Sadly have to do something to make a living after graduation :(
As a graduate student I always felt poor and hard pressed for time (didn't we all?), I had no idea how much worse things would get after graduation (in terms of time and money to pursue one's own interests)... still, Gambit is simply too cool not to try to push some part of it forward.
I think that the discussion between Marc and Bradley is very interesting; reminds me of debates along the line of "the code's not done until it's documented" versus "the code IS the documentation", that crop up in smaller coding shops all the time. I've been snooping through the Gambit code for a while now, and I've crawled through LambdaNative in detail (LN has fantastic potential as a development platform - but I agree with Bradley - it wasn't easy to get started).
It is not clear to me how to contribute to documentation in a maintainable way. It sucks documenting code that changes under one's feet - that's just wasted effort. I guess my two big questions regarding documentation are:
What is expected in terms of documentation? Is there any part of the Gambit code that is adequately documented, so I can see what people are hoping for?
What would have the most impact - commenting inside the source code, or external documentation (perhaps a wiki), or something hybrid, like encoded comments inside the source code that could be "compiled" to viewable comments, similar to, for example, Javadocs)?
In terms of development, I think that a lot of momentum could be leveraged from having useful libraries available for Gambit. I haven't looked at define-library, but does it represent a forward-looking means to build libraries? It's unfortunate that scheme hasn't really resolved the module / library issue in a widely-standardised way - this inhibits library development. (Viva SchemeSpheres!)
On Thu, July 23, 2015 5:58 pm, Meng Zhang wrote:
Yeah a deep understanding of Gambit internal system would be really helpful when dealing with any macrology / module systems..
My last attempt was mostly an rewrite against riaxpander line by line in gambit and it's https://github.com/wsxiaoys/nova/blob/master/nova.scm mostly working (successfully loading chibi's init.scm and passed its r7rs test suite). While to produce more informative syntax mistake, it needs work to dive into gambit's source handling & internal symbols management..
Sadly have to do something to make a living after graduation :(
On Thu, Jul 23, 2015 at 2:40 PM, Álvaro Castro-Castilla alvaro.castro.castilla@gmail.com wrote:
On Thu, Jul 23, 2015 at 10:54 PM, Marc Feeley feeley@iro.umontreal.ca wrote:
On Jul 23, 2015, at 3:24 PM, Bradley Lucier lucier@math.purdue.edu wrote:
How does one use the "define-library" form? Is there documentation
somewhere, or does one just guess from the examples in that git repository?
I think the topic of this thread is very important indeed. I completely relate to Marc's position: there is only so much you can do. And eventually we all have to do something to make a living, which unfortunately for many of us is not 100% Gambit-related.
Also, SchemeSpheres is ready to use R7RS as soon as Gambit implements it. It sits a layer above that, and uses a custom version of psyntax and R7RS to get the minimal support to be functional and usable now.
On Thu, Jul 23, 2015 at 10:58:13PM -0400, William Soukoreff wrote:
What would have the most impact - commenting inside the source code, or external documentation (perhaps a wiki), or something hybrid, like encoded comments inside the source code that could be "compiled" to viewable comments, similar to, for example, Javadocs)?
I've found most automatically generated documentation to be nearly worthless.
That said, I think that documentation should be located together with the code it documents, and extracted with an automatic documentation engine.
The point is that the documentation still needs to be written. By people who care that the final product is readable, clear, and pricise. But it needs also to be close to the code, so that it can be updated when its code is updated.
There also have to be introductory sections that tie everything together. These sections often do not belong with any source-code component of the source code. They are essential for someone approaching the system for the first time.
My example of exquisite documentation produced by a documentation generator is the Trestle Reference Manual:
http://www.std.org/~msm/common/SRC-RR-068.pdf
If you look at the source code for Trestle, you'll find the source code for the manual there, ofter interspersed in the interface files. I'm sure that getting it to be coherent when extracted and displayed took significant effort in the design of the documentation generator and in the source code of the documented modules.
The immediate practical question in this approach is:
How can we organise a crowd-sourced effort to accomplish this? A wiki is the usual answer, but it fails in terms of integration with the source code, which is essential to keeping it up-to-date with code changes.
I'd almost want the source-code to be on the wiki, so that people can edit comments right into it. And some mechanism should be available to merge these changes into the official source code, with some automatic filter that will ensure that none of the chages can affect source code behaviour. Maybe on that checks that chages are only made to comments, or other similar none-active code.
Changes that do not conform to this should be returned to the submitter (in his own revision conttrol branch) for reworking, or, after that, for review as a formal patch to the active code.
This might be a nontrivial add-on to revision control.
-- hendrik
On Fri, Jul 24, 2015 at 6:46 PM, Hendrik Boom hendrik@topoi.pooq.com wrote:
On Thu, Jul 23, 2015 at 10:58:13PM -0400, William Soukoreff wrote:
What would have the most impact - commenting inside the source code, or
external
documentation (perhaps a wiki), or something hybrid, like encoded
comments inside
the source code that could be "compiled" to viewable comments, similar
to, for
example, Javadocs)?
I've found most automatically generated documentation to be nearly worthless.
That said, I think that documentation should be located together with the code it documents, and extracted with an automatic documentation engine.
The point is that the documentation still needs to be written. By people who care that the final product is readable, clear, and pricise. But it needs also to be close to the code, so that it can be updated when its code is updated.
I agree completely.
There also have to be introductory sections that tie everything together. These sections often do not belong with any source-code component of the source code. They are essential for someone approaching the system for the first time.
High-level view of the project is as important as the low-level documentation of the specific techniques used.
My example of exquisite documentation produced by a documentation generator is the Trestle Reference Manual:
http://www.std.org/~msm/common/SRC-RR-068.pdf
If you look at the source code for Trestle, you'll find the source code for the manual there, ofter interspersed in the interface files. I'm sure that getting it to be coherent when extracted and displayed took significant effort in the design of the documentation generator and in the source code of the documented modules.
Amazing.
The immediate practical question in this approach is:
How can we organise a crowd-sourced effort to accomplish this? A wiki is the usual answer, but it fails in terms of integration with the source code, which is essential to keeping it up-to-date with code changes.
I think the best way would be to use the pull-request/review approach on github. It's a common way of doing it, and it works well for making sure of consistency. Contributors fork and add changes to documentation in a branch, then open pull request. This PR will be reviewed and merged by Marc and other "core" contributors of Gambit, as in many opensource projects.
Key to this would be that a general structure is first laid in place.
This can be implemented with Scribble, markdown or anything in those lines.
Re "how to document Gambit's inner workings":
I guess the videoconference is the first real more complete understanding - this time into the IO subsystem - that the community gets.
Informal documents or writeups, even just dropped as email here on the ML, will go a long way.
(The totality of documentation right now is pretty much http://dynamo.iro.umontreal.ca/wiki/index.php/Internal_Documentation , so every line of documentation published on the ML will be a milestone :) )
2015-07-24 19:14 GMT+02:00 Álvaro Castro-Castilla < alvaro.castro.castilla@gmail.com>:
On Fri, Jul 24, 2015 at 6:46 PM, Hendrik Boom hendrik@topoi.pooq.com wrote:
On Thu, Jul 23, 2015 at 10:58:13PM -0400, William Soukoreff wrote:
What would have the most impact - commenting inside the source code, or
external
documentation (perhaps a wiki), or something hybrid, like encoded
comments inside
the source code that could be "compiled" to viewable comments, similar
to, for
example, Javadocs)?
I've found most automatically generated documentation to be nearly worthless.
That said, I think that documentation should be located together with the code it documents, and extracted with an automatic documentation engine.
The point is that the documentation still needs to be written. By people who care that the final product is readable, clear, and pricise. But it needs also to be close to the code, so that it can be updated when its code is updated.
I agree completely.
There also have to be introductory sections that tie everything together. These sections often do not belong with any source-code component of the source code. They are essential for someone approaching the system for the first time.
High-level view of the project is as important as the low-level documentation of the specific techniques used.
My example of exquisite documentation produced by a documentation generator is the Trestle Reference Manual:
http://www.std.org/~msm/common/SRC-RR-068.pdf
If you look at the source code for Trestle, you'll find the source code for the manual there, ofter interspersed in the interface files. I'm sure that getting it to be coherent when extracted and displayed took significant effort in the design of the documentation generator and in the source code of the documented modules.
Amazing.
The immediate practical question in this approach is:
How can we organise a crowd-sourced effort to accomplish this? A wiki is the usual answer, but it fails in terms of integration with the source code, which is essential to keeping it up-to-date with code changes.
I think the best way would be to use the pull-request/review approach on github. It's a common way of doing it, and it works well for making sure of consistency. Contributors fork and add changes to documentation in a branch, then open pull request. This PR will be reviewed and merged by Marc and other "core" contributors of Gambit, as in many opensource projects.
Key to this would be that a general structure is first laid in place.
This can be implemented with Scribble, markdown or anything in those lines.
Gambit-list mailing list Gambit-list@iro.umontreal.ca https://webmail.iro.umontreal.ca/mailman/listinfo/gambit-list
On Fri, Jul 24, 2015 at 07:14:47PM +0200, Álvaro Castro-Castilla wrote:
On Fri, Jul 24, 2015 at 6:46 PM, Hendrik Boom hendrik@topoi.pooq.com wrote:
My example of exquisite documentation produced by a documentation generator is the Trestle Reference Manual:
http://www.std.org/~msm/common/SRC-RR-068.pdf
If you look at the source code for Trestle, you'll find the source code for the manual there, ofter interspersed in the interface files. I'm sure that getting it to be coherent when extracted and displayed took significant effort in the design of the documentation generator and in the source code of the documented modules.
Amazing.
Just to show what is really technically feasible.
We may have to settle for less, we may be used to making do with less, but something like this is what to aim for.
-- hendrik
On Thu, Jul 23, 2015 at 10:58:13PM -0400, William Soukoreff wrote:
In terms of development, I think that a lot of momentum could be leveraged from having useful libraries available for Gambit. I haven't looked at define-library, but does it represent a forward-looking means to build libraries? It's unfortunate that scheme hasn't really resolved the module / library issue in a widely-standardised way - this inhibits library development. (Viva SchemeSpheres!)
Does r7rs have anything useful to add to this iissue?
-- hendrik
On Thu, Jul 23, 2015 at 10:58:13PM -0400, William Soukoreff wrote:
What would have the most impact - commenting inside the source code, or external documentation (perhaps a wiki), or something hybrid, like encoded comments inside the source code that could be "compiled" to viewable comments, similar to, for example, Javadocs)?
Whatever is used, it should be something that can be compiled to an elegant document.
The documentation source code should be edited as plain ASCII or UTF-8 text No trivial layout changes such as changing line boundarise to make it look pretty should be made in the source code -- this kind of thing, though it looks good, does not play well with revision control.
Markdown is popular for this. Asciidoc is possibly better because it is designed for making books rather than blog entries. Scribble (from the Racket project) has the advantage of being Scheme-based, so it's possible to write Scheme programs to produce text where appropriate.
Note that Scribble-based documentation might fit well into Scheme source code, especially if there were some mechanism to filter it in or out of a partiular execution or compilation.
-- hendrik