pantry/README.md

100 lines
2.8 KiB
Markdown
Raw Normal View History

2023-09-30 19:15:42 +03:00
![pkgx](https://pkgx.dev/banner.png)
2023-02-11 14:06:35 +03:00
2023-09-30 19:15:42 +03:00
pkg metadata and build instructions.
2022-11-01 15:31:22 +03:00
# Contributing
2023-09-30 19:15:42 +03:00
Assuming you have `pkgx` with shell integration:
2023-02-15 14:16:02 +03:00
2023-02-11 14:06:35 +03:00
```sh
2023-09-30 19:15:42 +03:00
$ git clone https://github.com/pkgxdev/pantry
2023-02-11 14:06:35 +03:00
$ cd pantry
2023-09-30 19:15:42 +03:00
2023-10-11 14:19:52 +03:00
$ dev # https://docs.pkgx.sh/dev
# ^^ IMPORTANT! Otherwise the `pkg` command cannot be found
2023-02-11 14:06:35 +03:00
2023-02-12 19:57:17 +03:00
$ pkg init
2023-02-11 14:06:35 +03:00
# ^^ creates a “wip” package.yml
2023-02-12 19:57:17 +03:00
# ^^ if you already know the name, you can pass it as an argument
2023-02-11 14:06:35 +03:00
2023-02-12 19:57:17 +03:00
$ pkg edit
2023-02-11 14:06:35 +03:00
# ^^ opens the new package.yml in your EDITOR
2023-02-12 19:57:17 +03:00
$ pkg build
2023-09-30 19:15:42 +03:00
# builds to `./builds`
2023-02-15 14:16:02 +03:00
# ^^ needs a zero permissions GITHUB_TOKEN to use the GitHub API
# either set `GITHUB_TOKEN` or run `gh auth login`
2023-02-11 14:06:35 +03:00
$ foo
# ^^ anything in the `provides:` key will now run
2023-02-12 19:57:17 +03:00
$ pkg test
2023-02-11 14:06:35 +03:00
# ^^ you need to write a test that verifies the package works
$ gh repo fork
$ git branch -m my-new-package
$ git push origin my-new-package
$ gh pr create
```
2023-03-09 19:49:03 +03:00
> * `pkg build` and `pkg test` take a `-L` flag to run in a Linux Docker container
> * All commands take an optional pkg-spec eg. `pkg build zlib.net^1.1`
2023-02-15 14:16:02 +03:00
2023-09-30 19:15:42 +03:00
While inside the pantry `dev` environment you can run commands from any built
packages provided you specified their `provides:` key.
2023-10-11 14:19:52 +03:00
## BrewKit
We use a special package called [`brewkit`] to build packages both here and
in CI/CD. `brewkit` provides the `pkg` command.
## GitHub Codespaces
`pantry` also works in GitHub Codespaces. The default configuration
2023-09-30 19:15:42 +03:00
provides with the repository will install/update `pkgx` at the time
you attach, so you should be able to quickly work on or test packages
in a remote linux environment (or work from a device with just a web browser).
2023-02-11 14:06:35 +03:00
## Packaging Guide
Packaging can be cumbersome.
Our [wiki] is our packaging knowledge base.
For other assistance, start a [discussion].
2023-10-11 14:19:52 +03:00
The best way to figure out solutions for your problems is to read other
examples from the pantry.
2023-02-11 14:06:35 +03:00
## After Your Contribution
We build “bottles” (tard binaries) and upload them to our CDN. Thus your
contribution will be available at merge-time + build-time. `pkgx` should
automatically sync the pantry to your local machine if you ask for something
it doesnt know about, but in the case where that fails do a `pkgx --sync`
first.
2023-02-11 14:06:35 +03:00
2023-09-30 19:15:42 +03:00
The pantry automatically builds new releases of packages *as soon as they are
2023-02-11 14:06:35 +03:00
released* (usually starting the builds within seconds). There is no need to
submit PRs for updates.
2023-02-26 17:35:02 +03:00
## Working on Other Peoples Pull Requests
Packaging can be fiddly so we all pitch in. If you want to help someone else
with their pull request then you can use GitHubs CLI:
```
$ gh pr checkout 123
# or you can copy paste the URL:
2023-09-30 19:15:42 +03:00
$ gh pr checkout https://github.com/pkgxdev/pantry/pull/123
# then open for editing:
$ pkg edit
2023-02-26 17:35:02 +03:00
```
2023-02-11 14:06:35 +03:00
2023-09-30 19:15:42 +03:00
[wiki]: https://github.com/pkgxdev/pantry/wiki
[discussion]: https://github.com/orgs/pkgxdev/discussions
2023-02-11 14:06:35 +03:00
[IPFS]: https://ipfs.tech
2023-05-04 17:25:10 +03:00
[`npmjs.com/provider.yml`]: ./projects/npmjs.com/provider.yml