CONTRIBUTING.md · rowtype-yoga/package-sets

git.iko.soy/rowtype-yoga/package-sets

on psc-0.14.5-20211111 help sign in

rowtype-yoga/package-sets/CONTRIBUTING.md

205 lines 8.9 kB history raw

1# Contributing to `package-sets`

3This document is meant to be a general guide and FAQ for contributors to this repo.

5It defines some policies that are applied, and details how to add new packages and the criteria packages should match to stay in the set.

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)

21## General

23All changes go through pull requests.

25All packages that are included in the set must be either:

26- on the `bower` registry, i.e. `bower i $your-package` must run successfully

27- or listed in the [new-packages] in the `registry` repo.

29The bottom line is that we need to prevent divergence in the ecosystem - e.g. having two different codebases for a package called "prelude" - and this means having a "central registry of package names".

30The Bower registry used to be that, but [recently it has stopped accepting package submissions][no-bower], which led to the current situation. This will change hopefully soon, as we move to a PureScript-only registry.

32Packages must comply with the following criteria. The `pulp` commands listed below are used because they handle most of the work for you:

33- `bower i -p` must run successfully.

34 This command installs your dependencies and excludes any 'devDependencies'.

35- _You must use `pulp version` to version your package._

36 This guarantees that the tag will start with the `v` prefix.

37- _Your package should be included in the [`purescript/registry`][registry] repo._

38 It should be listed either in [`new-packages.json`][new-packages], or in `bower-packages.json` (for packages living on the Bower registry).

39- _You must use `pulp publish` to publish your package._

40 This command will check that everything is in order, and publish your documentation to Pursuit.

42## Releases

44A "release" of the package set consists in a *git tag* (i.e. what GitHub calls a release).

46Releases 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].

47This implies that the `master` branch should always be "release ready".

49Releases have the following naming convention:

50```

51psc-${compiler-version}-${date}

52```

54Where:

55- `compiler-version` is the version of the compiler supported by the package-set.

56 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`.

57- `date` is the release date, in `yyyyMMdd` format.

59## Will any package be dropped at any point?

61For 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.

63This 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)

65However, 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.

67Once a package version introduces breakage, the upstream will be notified (via issue or pull request) and a package might be removed from the set if there is no activity after 1 week.

69## Package-sets maintenance

71Once one displays sustained interest in the project, they can ask to help maintaining it.

72You can do so by [opening an issue][issues]

74## How to add a package to the set

76### Prerequisites

78To hack on this project, it should be enough to have [nix](https://nixos.org/nix/download.html) installed. You can verify your changes with

80 nix-shell --command make

83If you're unable to run Nix but able to run `docker`, then you can achieve the same result with the following:

85 docker run -t --mount type=bind,source="$(pwd)",target=/package-sets nixos/nix /bin/sh -c 'cd /package-sets; nix-shell --run "make"'

88### TL;DR

90The following section will detail how to add a package to the package-set.

92The *TL;DR* about it is:

93- add the Dhall package definition in some `src/groups/${username}.dhall` (where `username` is the one of the author of the package)

94- if adding a new group file, also add a new line containing `⫽ ./groups/${username}.dhall` to `src/packages.dhall`

95- run `make` and `cd src && spago verify ${your-new-package-name}`

97### 0. Background knowledge

99#### Why/how Dhall?

100

101[Dhall](https://github.com/dhall-lang/dhall-lang) is a programming language that guarantees

102termination. Its most useful characteristics for uses in this project are:

103* Static typing with correct inference: unlike the `packages.json` file, we have the compiler check that we correctly define packages

104* Functions: we can use functions to create simple functions for defining packages

105* Local and remote path importing: we can use this to mix and match local and remote sources as necessary to build package sets

106* Typed records with directed merging: we can use this to split definitions into multiple groupings and apply patching of existing packages as needed

107

108Let's look at the individual parts for how this helps us make a package-set.

109

110#### Brief detour of how the package-set is structured

111

112The files in this package-set are structured as such:

113

114```

115-- Package type definition

116src/Package.dhall

117

118-- packages to be included when building package set

119src/packages.dhall

120

121-- package "groups" where packages are defined in records

122src/groups/[...].dhall

123```

124

125The `Package.dhall` contains the simple type that is the definition of a package:

126

127```hs

128{ dependencies : List Text, repo : Text, version : Text }

129```

130

131So a given package is nothing more than:

132- a list of dependencies

133- the git url for the repository

134- and the tag or branch that it can be pulled from.

135

136The `packages.dhall` is the actual "package-set": a record from package names to package definitions.

137It is defined by taking package definitions from the groups and joining them with a right-sided merge.

138This is the file used to generate the `packages.json`.

139

140

141```hs

142 ./groups/purescript.dhall

143// ./groups/purescript-contrib.dhall

144// ./groups/purescript-web.dhall

145// ./groups/purescript-node.dhall

146// ...

147// ./groups/justinwoo.dhall

148```

149

150### 1. Adding a new package

151

152To add a new package to the package set, you should create a package definition matching the Package type, and put it in the group file corresponding to the author's username.

153

154For example, if I wish to add to the package-set the version `v4.2.0` of the package `some-food` from `someauthor`, I will create the file `src/groups/someauthor.dhall`.

155

156Its content would look something like this:

157

158```hs

159{ some-food =

160 { dependencies =

161 [ "event", "prelude", "record", "typelevel-prelude" ]

162 , repo =

163 "https://github.com/someauthor/purescript-some-food.git"

164 , version =

165 "v4.2.0"

166 }