GitHub ‘template repository’ functionality

[Stephen De Gabrielle]

Hi, 

GitHub recently introduced a ‘template repository’ functionality https://help.github.com/en/articles/creating-a-template-repository

I’ve created a draft of a Racket version and would appreciate your feedback.

draft template repo: https://github.com/spdegabrielle/racket-package

‘generate’ link:  https://github.com/spdegabrielle/racket-package/generate

I suspect I've put too much in - I think the template should only have the things that `raco pkg new` doesn't do. 

Kind regards

Stephen

PS: I know gitlab has a similar functionality but I am less experienced with that platform  

[Ryan Kramer]

Thanks Stephen, this looks useful.

I don't understand why you say "I think the template should only have the things that `raco pkg new` doesn't do." Wouldn't the intent be that I use the template to create my own repo, clone it onto my local machine, and then run `raco pkg install`? In that case, I think you would want the stuff from `raco pkg new`. (But my knowledge of packages and collections is just-enough-to-get-by.)

I recently struggled converting a repository from a single to a multi-collection package. (And I still have some learning and cleanup to do.) It might be nice to have a template for a simple multi-collection repo also. Maybe with lib, doc, and test collections? On the other hand, maybe multi-collection packages are too different for a template to make sense.

[Stephen De Gabrielle]

Hi Ryan, 

On Fri, Aug 9, 2019 at 8:10 PM Ryan Kramer <default...@gmail.com> wrote:

Thanks Stephen, this looks useful.

I don't understand why you say "I think the template should only have the things that `raco pkg new` doesn't do." Wouldn't the intent be that I use the template to create my own repo, clone it onto my local machine, and then run `raco pkg install`? In that case, I think you would want the stuff from `raco pkg new`. (But my knowledge of packages and collections is just-enough-to-get-by.)

Thats not bad, but the more look at `raco pkg new` the more I realise how good it is! - It knows I'm the author in addition to the name of the package and populates the template files accordingly. Some examples below for the command `raco pkg new orlando`

`new.rkt` is also pretty easy to extend - take a look at the code: https://github.com/racket/racket/blob/master/racket/collects/pkg/private/new.rkt

The other factors on my mind are;

a) Also GitHub are a big organisation (we don't even rate a .gitignore template. ) - relying on a giant who doesn't even know you exist isn't nice position.

b) Not everyone wants to use GitHub. There are other providers. e.g. GitLab is also good. Some racketeers have very good reasons to not use GitHub.

I think a good template that learns from my mistakes would..

..include generic git configuration (.gitignore)

..have GitHub/Lab/etc versions activate relevant features for those platforms  (.github .gitlab etc.)

..have a readme that tells you how to; add raco to your $path, run `raco pkg new <package name> `, register on https://pkgs.racket-lang.org etc. (similar  guidance is already in place in the `main.rkt` as generated by `raco pkg new` )

I recently struggled converting a repository from a single to a multi-collection package. (And I still have some learning and cleanup to do.) It might be nice to have a template for a simple multi-collection repo also. Maybe with lib, doc, and test collections? On the other hand, maybe multi-collection packages are too different for a template to make sense.

I think a template for each is good idea. Maybe you could use your multi-collection package as a starting point?

I'm not sure how `new.rkt` could be extended to support this - but making a template can help others in the meantime, and provides a sketch of what you would want `raco pkg new multi` to do in the future. (maybe templates for web & gui apps too?)

Kind regards,

Stephen

examples of output of  `raco pkg new orlando`: 

#lang scribble/manual
@require[@for-label[orlando
                    racket/base]]
@title{orlando}
@author{spdegabrielle}
@defmodule[orlando]
Package Description Here

 

#lang info
(define collection "orlando")
(define deps '("base"))
(define build-deps '("scribble-lib" "racket-doc" "rackunit-lib"))
(define scribblings '(("scribblings/orlando.scrbl" ())))
(define pkg-desc "Description Here")
(define version "0.0")
(define pkg-authors '(spdegabrielle))  

[Ryan Kramer]

Ah, that makes sense. I guess I didn't realize (or took for granted) that `raco pkg new` was doing all that. With that in mind, it certainly does make more sense to run `raco pkg new` locally.