git.iko.soy/rowtype-yoga/package-sets
on master help sign in
Update docs (#277)

This is a general adjustment of documentation after the Spacchetti merge. It includes: - a rewrite of the README to detail only how to use the package-set - the addition of CONTRIBUTING.md to detail some contribution policies and a detailed example of how to add packages to the set (note that the examples are now in ascii) - the addition of table of contents for both the readme and the contribution guide Perhaps the most important part of this PR is the definition of some guidelines for the package-set, e.g.: - a policy for if/when packages are dropped from the set - a set of criterias new packages should comply with

commitdd59223dfe7e3b28afb6010d6c0288d36b84c89f authorFabrizio Ferrai <fabrizio.ferrai@gmail.com> dateSat 9 Mar 2019, 16:05 (8 years ago) parent4757aea
2 files changed+231โˆ’165
compare with master
unifiedsplit
CONTRIBUTING.md+188 README.md+43โˆ’165
CONTRIBUTING.mdnew file+188
@@ -0,0 +1,188 @@
1+# Contributing to `package-sets`
2+
3+This document is meant to be a general guide and FAQ for contributors to this repo.
4+
5+It defines some policies that are applied, and details how to add new packages and the criteria packages should match to stay in the set.
6+
7+
8+- [General](#general)
9+- [Releases](#releases)
10+- [Will any package be dropped at any point?](#will-any-package-be-dropped-at-any-point)
11+- [Package-sets maintenance](#package-sets-maintenance)
12+- [How to add a package to the set](#how-to-add-a-package-to-the-set)
13+ - [0. Background knowledge](#0-background-knowledge)
14+ - [Why/how Dhall?](#whyhow-dhall)
15+ - [Brief detour of how the package-set is structured](#brief-detour-of-how-the-package-set-is-structured)
16+ - [Prerequisites](#prerequisites)
17+ - [1. Adding a new package](#1-adding-a-new-package)
18+ - [2. Verifying a package](#2-verifying-a-package)
19+
20+
21+## General
22+
23+All changes go through pull requests.
24+
25+There are some criteria that packages being added should comply with:
26+- _You should use `pulp version` to version your package._
27+ The reason is that the tag should start with the `v` prefix
28+- _You should use `pulp publish` to publish your package._
29+ The reason is that since there are two distribution methods for packages (the Bower registry and the package sets), we rely on the Bower registry to act as a "central registry of package names" for both methods, in order to prevent divergence in the ecosystem (e.g. having two different codebases for a package called "prelude")
30+- `bower i -p` should run successfully
31+
32+## Releases
33+
34+A "release" of the package set consists in a *git tag* (i.e. what GitHub calls a release).
35+
36+Releases happen quite often (look at the [release history][releases]), and anyone can request a new release at any time, by just [opening an issue][issues].
37+This implies that the `master` branch should always be "release ready".
38+
39+Releases have the following naming convention:
40+```
41+psc-${compiler-version}-${date}
42+```
43+
44+Where:
45+- `compiler-version` is the version of the compiler supported by the package-set.
46+ Support for different versions of the compiler is implied by SemVer, e.g. if a package-set is compatible with `0.12.2`, then it will be compatible with `0.12.3`, but not `0.12.1` or `0.13.0`.
47+- `date` is the release date, in `yyyyMMdd` format.
48+
49+## Will any package be dropped at any point?
50+
51+For package-sets to be able to keep up with the new releases in the ecosystem, package maintainers should strive for having their packages work with the latest versions of dependencies.
52+
53+This is because if packages `X@v1` and `Y@v1` depend on package `Z@v1` then if package X releases `v2` that depends on `Z@v2`, then also package Y should be updated to depend on it. (this is because a package-set contains only *one* version of every package)
54+
55+However, things happen and packages go unmaintained, so there's the need to drop packages from the package-set every once in a while, in order to allow for the majority of the packages to keep up with the latest versions.
56+
57+Since package-set releases are tied to compiler releases, new compiler releases (happening every 6 weeks) will coincide with outdated packages being dropped from the set.
58+
59+## Package-sets maintenance
60+
61+Once one displays sustained interest in the project, they can ask to help maintaining it.
62+You can do so by [opening an issue][issues]
63+
64+## How to add a package to the set
65+
66+The following section will detail how to add a package to the package-set.
67+
68+The *TL;DR* about it is:
69+- add the Dhall package definition in some `src/groups/${username}.dhall` (where `username` is the one of the author of the package)
70+- run `make setup` and `psc-package verify ${your-new-package-name}`
71+
72+### 0. Background knowledge
73+
74+#### Why/how Dhall?
75+
76+[Dhall](https://github.com/dhall-lang/dhall-lang) is a programming language that guarantees
77+termination. Its most useful characteristics for uses in this project are:
78+* Static typing with correct inference: unlike the `packages.json` file, we have the compiler check that we correctly define packages
79+* Functions: we can use functions to create simple functions for defining packages
80+* Local and remote path importing: we can use this to mix and match local and remote sources as necessary to build package sets
81+* Typed records with directed merging: we can use this to split definitions into multiple groupings and apply patching of existing packages as needed
82+
83+Let's look at the individual parts for how this helps us make a package-set.
84+
85+#### Brief detour of how the package-set is structured
86+
87+The files in this package-set are structured as such:
88+
89+```
90+-- Package type definition
91+src/Package.dhall
92+
93+-- function to define packages
94+src/mkPackage.dhall
95+
96+-- packages to be included when building package set
97+src/packages.dhall
98+
99+-- package "groups" where packages are defined in records
100+src/groups/[...].dhall
101+```
102+
103+The `Package.dhall` contains the simple type that is the definition of a package:
104+
105+```hs
106+{ dependencies : List Text, repo : Text, version : Text }
107+```
108+
109+So a given package is nothing more than:
110+- a list of dependencies
111+- the git url for the repository
112+- and the tag or branch that it can be pulled from.
113+
114+The `mkPackage.dhall` contains a function for creating `Package` values easily:
115+
116+```hs
117+ \(dependencies : List Text)
118+-> \(repo : Text)
119+-> \(version : Text)
120+-> { dependencies = dependencies, repo = repo, version = version }
121+ : ./Package.dhall
122+```
123+
124+The `packages.dhall` is the actual "package-set": a record from package names to package definitions.
125+It is defined by taking package definitions from the groups and joining them with a right-sided merge.
126+This is the file used to generate the `packages.json`.
127+
128+
129+```hs
130+ ./groups/purescript.dhall
131+// ./groups/purescript-contrib.dhall
132+// ./groups/purescript-web.dhall
133+// ./groups/purescript-node.dhall
134+// ...
135+// ./groups/justinwoo.dhall
136+```
137+
138+#### Prerequisites
139+
140+In order to hack on this project, you should have installed:
141+- [dhall][dhall]
142+- [psc-package][psc-package]
143+- [jq][jq]
144+
145+### 1. Adding a new package
146+
147+To add a new package to the package set, you should create a package definition with `mkPackage`, and put it in the group file corresponding to the author's username.
148+
149+For example, if I wish to add to the package-set the version `v4.2.0` of the package `unicorns` from `someauthor`, I will create the file `src/groups/someauthor.dhall`.
150+
151+Its content would look something like this:
152+
153+```hs
154+ let mkPackage = ./../mkPackage.dhall
155+
156+in { unicorns =
157+ mkPackage
158+ [ "prelude"
159+ , "console"
160+ , "simple-json"
161+ ]
162+ "https://github.com/someauthor/purescript-unicorns.git"
163+ "v4.2.0"
164+ }
165+```
166+
167+
168+### 2. Verifying a package
169+
170+After adding your package to the Dhall files, you should check that the package-set is still consistent.
171+
172+In order to verify the addition (or change), you should follow these steps:
173+- `make setup`: this will setup a test project based on the new package-set
174+- `psc-package verify ${your-new-package-name}`
175+
176+Once it verifies correctly, you should check in both the Dhall files and the `packages.json`
177+
178+You're now ready to commit! ๐Ÿ™‚
179+
180+[jq]: https://github.com/stedolan/jq
181+[psc-package]: https://github.com/purescript/psc-package/
182+[dhall]: https://github.com/dhall-lang/dhall-haskell
183+[releases]: https://github.com/purescript/package-sets/releases
184+[issues]: https://github.com/purescript/package-sets/issues
185+[local-setup]: https://github.com/spacchetti/spago#i-still-want-to-use-psc-package-can-this-help-me-in-some-way
186+[spago]: https://github.com/spacchetti/spago
187+[bower]: https://bower.io/
188+[pulp]: https://github.com/purescript-contrib/pulp
README.md+43โˆ’165
@@ -1,33 +1,40 @@
1โˆ’# Package-Sets
1+# Package Sets
22
33[![Build Status](https://travis-ci.org/purescript/package-sets.svg?branch=master)](https://travis-ci.org/purescript/package-sets)
44
5โˆ’PureScript package sets for Psc-Package, aka "Spacchetti"
5+A curated list of PureScript packages for Psc-Package and Spago
66
77![](https://i.imgur.com/roCuNQ9.png)
88
9โˆ’Dhall-driven package sets, made for forking and modifying easily.
109
11โˆ’Historically, this was a separate project created by Justin Woo called "Spacchetti" (as in Spagghetti + Pacchetti). This has now merged into package-sets, but is still referred to as "Spacchetti" in many resources.
10+- [What is a package-set?](#what-is-a-package-set)
11+- [Add your package](#add-your-package)
12+- [How do I use package-sets with `psc-package`?](#how-do-i-use-package-sets-with-psc-package)
13+- [How do I use package-sets with `spago`?](#how-do-i-use-package-sets-with-spago)
1214
13โˆ’## Introduction to Psc-Package (from a Package-Sets perspective)
1415
15โˆ’### What is Psc-Package?
16+## What is a package set?
1617
17โˆ’[Psc-Package](https://github.com/purescript/psc-package/) is a package manager for PureScript that works essentially by running a bunch of git commands. Its distinguishing feature from most package managers is that it uses a **package set**.
18+A package set is a **collection** of packages, such that there is only **one** entry (i.e. version) for a given package in the set.
1819
19โˆ’### What is a Package Set?
20+If you use a package manager based on package-sets, this means that when you want to install a package:
21+- it must be in the package set
22+- its dependencies and all the transitive dependencies must be in the package set
2023
21โˆ’Many users trying to rush into using Psc-Package don't slow down enough to learn what package sets are. They are a **set** of packages, such that the package set only contains **one** entry for a given package in a set. This means that
24+## Add your package
2225
23โˆ’* Whichever package you want to install must be in the package set
24โˆ’* The dependencies and the transitive dependencies of the package you want to install must be in the package set
26+This repository aims to be a good collection of packages you can depend on.
27+In general we welcome all packages, provided that they follow some guidelines defined in the [contributing guide](#CONTRIBUTING.md).
2528
26โˆ’Package sets are defined in `packages.json` in the root of any package set repository, like in <https://github.com/purescript/package-sets/blob/master/packages.json>.
29+The linked document also contains instructions on how to add new packages to the set, and information on versioning and related policies.
2730
28โˆ’### How are package sets used?
31+## How do I use `package-sets` with Psc Package?
2932
30โˆ’Package sets are consumed by having a `psc-package.json` file in the root of your project, where the contents are like below:
33+[`psc-package`][psc-package] is a package manager for PureScript that works essentially by running a bunch of git commands. Its distinguishing feature from most package managers is that it uses a **package set**.
34+
35+`psc-package` will use as package-set the `packages.json` file in the root of any package-set repository, like in [this case][packages-json].
36+
37+In order to use a package-set, the `psc-package.json` file in the root of your project, should look something like this:
3138
3239```json
3340{
@@ -42,178 +49,49 @@ Package sets are consumed by having a `psc-package.json` file in the root of you
4249}
4350```
4451
45โˆ’So the way this file works is that
52+The way this file works is that:
53+- `"set"` matches the tag or branch of the git repository of the package set
54+- `"source"` is the URL for the git repository of the package set
55+- `"depends"` is an array of strings, where the strings are names of packages you depend on.
56+ *Note:* as said above, these dependencies should be contained in the package-set
4657
47โˆ’* `"set"` matches the tag or branch of the git repository of the package set
48โˆ’* `"source"` is the URL for the git repository of the package set
49โˆ’* `"depends"` is an array of strings, where the strings are names of packages you depend on
50โˆ’
51โˆ’When you run `psc-package install`, psc-package will perform the steps so that the following directory has the package set cloned to it:
58+When you run `psc-package install`, psc-package will perform the steps so that the following directory will have the package set cloned into it:
5259
5360```
5461.psc-package/set-name/.set
5562```
5663
57โˆ’And the package set will be available in
64+And the package set will then be available in
5865
5966```
6067.psc-package/set-name/.set/packages.json
6168```
6269
63โˆ’When you install a package in your given package set, the directory structure will be used, such that if you install `aff` from your package set at version `v5.0.0`, you will have the contents of that package in the directory
70+When you install a package in your given package set, the package contents will be cloned in the following directory structure:
6471
6572```
66โˆ’.psc-package/set-name/aff/v5.0.0
67โˆ’```
68โˆ’
69โˆ’Once you understand these three sections, you'll be able to solve any problems you run into with Psc-Package.
70โˆ’
71โˆ’## Why/How Dhall?
72โˆ’
73โˆ’[Dhall](https://github.com/dhall-lang/dhall-lang) is a programming language that guarantees termination. Its most useful characteristics for uses in this project are
74โˆ’
75โˆ’* Static typing with correct inference: unlike the packages.json file, we have the compiler check that we correctly define packages
76โˆ’* Functions: we can use functions to create simple functions for defining packages
77โˆ’* Local and remote path importing: we can use this to mix and match local and remote sources as necessary to build package sets
78โˆ’* Typed records with directed merging: we can use this to split definitions into multiple groupings and apply patching of existing packages as needed
79โˆ’
80โˆ’Let's look at the individual parts for how this helps us make a package set.
81โˆ’
82โˆ’### Files
83โˆ’
84โˆ’The files in this package set are prepared as such:
85โˆ’
73+.psc-package/${set-name}/${package-name}/${tag}
8674```
87โˆ’-- Package type definition
88โˆ’src/Package.dhall
89โˆ’
90โˆ’-- function to define packages
91โˆ’src/mkPackage.dhall
9275
93โˆ’-- packages to be included when building package set
94โˆ’src/packages.dhall
76+E.g. in case of `aff@v5.0.0`:
9577
96โˆ’-- package "groups" where packages are defined in records
97โˆ’src/groups/[...].dhall
9878```
99โˆ’
100โˆ’#### `Package.dhall`
101โˆ’
102โˆ’This contains the simple type that is the definition of a package:
103โˆ’
104โˆ’```hs
105โˆ’{ dependencies : List Text, repo : Text, version : Text }
106โˆ’```
107โˆ’
108โˆ’So a given package has a list of dependencies, the git url for the repository, and the tag or branch that it can be pulled from.
109โˆ’
110โˆ’#### `mkPackage.dhall`
111โˆ’
112โˆ’This contains a function for creating `Package` values easily
113โˆ’
114โˆ’```hs
115โˆ’ ฮป(dependencies : List Text)
116โˆ’โ†’ ฮป(repo : Text)
117โˆ’โ†’ ฮป(version : Text)
118โˆ’โ†’ { dependencies = dependencies, repo = repo, version = version }
119โˆ’ : ./Package.dhall
120โˆ’```
121โˆ’
122โˆ’While this function is unfortunately stringly typed, this still lets us conveniently define packages without having to clutter the file with record definitions.
123โˆ’
124โˆ’#### `packages.dhall`
125โˆ’
126โˆ’This is the main file used to generate `packages.json`, and is defined by taking package definitions from the groups and joining them with a right-sided merge.
127โˆ’
128โˆ’```hs
129โˆ’ ./groups/purescript.dhall
130โˆ’โซฝ ./groups/purescript-contrib.dhall
131โˆ’โซฝ ./groups/purescript-web.dhall
132โˆ’โซฝ ./groups/purescript-node.dhall
133โˆ’-- ...
134โˆ’โซฝ ./groups/justinwoo.dhall
135โˆ’โซฝ ./groups/patches.dhall
136โˆ’```
137โˆ’
138โˆ’### Definitions and overrides
139โˆ’
140โˆ’As `patches.dhall` is last, its definitions override any existing definitions. For example, you can put an override for an existing definition of `string-parsers` with such a definition:
141โˆ’
142โˆ’```hs
143โˆ’ let mkPackage = ./../mkPackage.dhall
144โˆ’
145โˆ’in { string-parsers =
146โˆ’ mkPackage
147โˆ’ [ "arrays"
148โˆ’ , "bifunctors"
149โˆ’ , "control"
150โˆ’ , "either"
151โˆ’ , "foldable-traversable"
152โˆ’ , "lists"
153โˆ’ , "maybe"
154โˆ’ , "prelude"
155โˆ’ , "strings"
156โˆ’ , "tailrec"
157โˆ’ ]
158โˆ’ "https://github.com/justinwoo/purescript-string-parsers.git"
159โˆ’ "no-code-points"
160โˆ’ }
161โˆ’```
162โˆ’
163โˆ’## How to contribute to this package set
164โˆ’
165โˆ’### Requirements
166โˆ’
167โˆ’This project requires that you have at least:
168โˆ’
169โˆ’* [Dhall](https://github.com/dhall-lang/dhall-haskell) installed.
170โˆ’* [Psc-Package](https://github.com/purescript/psc-package/) installed, with the release binary in your PATH in some way.
171โˆ’* [jq](https://github.com/stedolan/jq) installed.
172โˆ’
173โˆ’### How to generate the package set after editing Dhall files
174โˆ’
175โˆ’First, test that you can actually run `make`:
176โˆ’
177โˆ’```sh
178โˆ’> make
179โˆ’formatted dhall files
180โˆ’generated to packages.json
181โˆ’```
182โˆ’
183โˆ’This is how you format Dhall files in the project and generate the `packages.json` that needs to be checked in. Unless you plan to consume only the `packages.dhall` file in your repository, you must check in `packages.json`.
184โˆ’
185โˆ’To actually use your new package set, you must create a new git tag and push it to your **fork of package-sets**. Then set your package set in your **project** repository accordingly, per EXAMPLE:
186โˆ’
187โˆ’```js
188โˆ’{
189โˆ’ "name": "EXAMPLE",
190โˆ’ "set": "160618", // GIT TAG NAME
191โˆ’ "source": "https://github.com/purescript/package-sets.git", // PACKAGE SET REPO URL
192โˆ’ "depends": [
193โˆ’ "console",
194โˆ’ "prelude"
195โˆ’ ]
196โˆ’}
79+.psc-package/set-name/aff/v5.0.0
19780```
19881
199โˆ’When you set this up correctly, you will see that running `psc-package install` will create the file `.psc-package/{GIT TAG NAME HERE}/.set/packages.json`.
200โˆ’
201โˆ’### Testing changes to package set
202โˆ’
203โˆ’To set up a test project, run `make setup`. Then you can test individual packages with `psc-package verify PACKAGE`.
204โˆ’
205โˆ’### Package set maintenance
206โˆ’
207โˆ’If you would like to help maintain Package-Sets, please get in touch with Justin via Twitter: <https://twitter.com/jusrin00>
208โˆ’
209โˆ’## Spago
82+## How do I use `package-sets` with `spago`?
21083
211โˆ’### Intro
84+[`spago`][spago] is a package manager and build tool for PureScript. It is very similar to `psc-package`, and the main differences are:
85+- it uses Dhall for its configuration (instead of `json` as `psc-package` does)
86+- it supports package overrides and additions directly in the project configuration
87+- it supports local dependencies (think `bower link`)
21288
213โˆ’Spago is a new CLI that can replace your usage of Psc-Package, using Dhall to configure your packages and your project.
89+With `spago` the package-set address is specified in the `upstream` variable of your local `packages.dhall`, which will usually import a remote `packages.dhall`, e.g. the one from this repo.
21490
215โˆ’See the Spago repo for more: <https://github.com/spacchetti/spago>
91+You can change the package-set version you are using by just pointing the `upstream` to a different location, and running `spago freeze` afterwards (see [its readme][spago] for more info about this)
21692
217โˆ’### Does Spago replace Psc-Package?
21893
219โˆ’Yes and no. See the Spago project for the full details on what it is and how it is the similar and different from Psc-Package: <https://github.com/spacchetti/spago>
94+[spago]: https://github.com/spacchetti/spago
95+[psc-package]: https://github.com/purescript/psc-package
96+[issues]: https://github.com/purescript/package-sets/issues
97+[packages-json]: https://github.com/purescript/package-sets/blob/master/packages.json