CONTRIBUTING.md · rowtype-yoga/package-sets

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

on psc-0.12.5-20190525 help sign in

rowtype-yoga/package-sets/CONTRIBUTING.md

202 lines 8.2 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 here must first be published via `bower` with no exceptions. 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. This prevents divergence in the ecosystem - e.g. having two different codebases for a package called "prelude".

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

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

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

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

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

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

33 This command will handle all of the publishing work for you.

35## Releases

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

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

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

42Releases have the following naming convention:

43```

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

45```

47Where:

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

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

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

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

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

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

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

60Since 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.

62## Package-sets maintenance

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

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

67## How to add a package to the set

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

71The *TL;DR* about it is:

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

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

74- run `make setup` and `psc-package verify ${your-new-package-name}`

76### 0. Background knowledge

78#### Why/how Dhall?

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

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

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

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

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

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

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

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

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

93```

94-- Package type definition

95src/Package.dhall

97-- function to define packages

98src/mkPackage.dhall

100-- packages to be included when building package set

101src/packages.dhall

102

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

104src/groups/[...].dhall

105```

106

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

108

109```hs

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

111```

112

113So a given package is nothing more than:

114- a list of dependencies

115- the git url for the repository

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

117

118The `mkPackage.dhall` contains a function for creating `Package` values easily:

119

120```hs

121 \(dependencies : List Text)

122-> \(repo : Text)

123-> \(version : Text)

124-> { dependencies = dependencies, repo = repo, version = version }

125 : ./Package.dhall

126```

127

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

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

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

131

132

133```hs

134 ./groups/purescript.dhall

135// ./groups/purescript-contrib.dhall

136// ./groups/purescript-web.dhall

137// ./groups/purescript-node.dhall

138// ...

139// ./groups/justinwoo.dhall

140```

141

142#### Prerequisites

143

144In order to hack on this project, you should have installed:

145- [dhall][dhall]

146- [psc-package][psc-package]

147- [jq][jq]

148

149### 1. Adding a new package

150

151To 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.

152

153For 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`.

154

155Its content would look something like this:

156

157```hs

158 let mkPackage = ./../mkPackage.dhall

159

160in { unicorns =

161 mkPackage

162 [ "prelude"

163 , "console"

164 , "simple-json"

165 ]