Skip to content

Commit f6902a5

Browse files
jaymzhfacebook-github-bot
jaymzh
authored and
facebook-github-bot
committed
Documents and sample configs for Universe Repos (facebook#334)
Summary: * Document how to build a Universe repo * Document requirements for _being_ a Universe repo * Provide sample configs and docs Closes facebook#315 Signed-off-by: Phil Dibowitz <phil@ipom.com> Pull Request resolved: facebook#334 Differential Revision: D79110653 fbshipit-source-id: 24dbdf75f9717854431601886b1158969d80dab9
1 parent ae8877b commit f6902a5

File tree

7 files changed

+347
-7
lines changed

7 files changed

+347
-7
lines changed

‎UNIVERSE.md‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -8,10 +8,10 @@ repo, so we make no guarantees about the state of repos in this file. We do
88
reserve the right to remove repos from this file which do not follow the
99
attribute-driven-API model.
1010

11-
* [Phil's FB API Style Cookbook
12-
Suite](https://github.com/jaymzh/chef-fb-api-cookbooks) - FB API Cookbooks
13-
from Phil (formerly Facebook Phil) that Meta doesn't wish to maintain
14-
* [Boxcutter cookbook suite for
15-
robotics](https://github.com/boxcutter/boxcutter-chef-cookbooks) -
16-
Facebook/Meta style cookbook suite for robotics that supports both
17-
AMD64/ARM64 platforms
11+
There are a variety of requirements for repos that appear here, be sure to
12+
read [CREATING_UNIVERSE_REPOS.md](docs/CREATING_UNIVERSE_REPOS.md).
13+
14+
| Name/Link | Prefix | Description |
15+
|------|--------|------|
16+
| [Phil's FB API Style Cookbook Suite](https://github.com/jaymzh/chef-fb-api-cookbooks) | pd | FB API Cookbooks from Phil (formerly Facebook Phil) that Meta doesn't wish to maintain |
17+
| [Boxcutter cookbook suite for robotics](https://github.com/boxcutter/boxcutter-chef-cookbooks) | boxcutter | Facebook/Meta style cookbook suite for robotics that supports both AMD64/ARM64 platforms |

‎docs/CREATING_UNIVERSE_REPOS.md‎

Lines changed: 193 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
How to create a Universe repo
2+
=============================
3+
4+
This document covers how to create a universe repo. The GitHub Actions
5+
workflows in this repo have been factored out for reusablity, to make sure all
6+
repos we reference will work well with the Facebook core cookbooks.
7+
8+
**BEFORE YOU START**: You'll need a prefix for your cookbooks. Check
9+
[UNIVERSE.md](../UNIVERSE.md) to ensure you're using a unique one.
10+
11+
Requirements
12+
------------
13+
14+
### Repo Layout
15+
16+
The repository should be layed out with the following top-level items:
17+
18+
* `cookbooks/` - a directory in which your cookbooks live
19+
* `scripts/` - a directory for local scripts
20+
* `README.md` - a README which should include specific things mentioned below
21+
* `CONTRIBUTING.md` - a document on how to contribute to your repo
22+
* `LICENSE` - A license file, see below for details
23+
24+
We also recommend `CODE_OF_CONDUCT.md`.
25+
26+
### API Requirements
27+
28+
Your cookbooks must follow the overall Facebook API model, which includes,
29+
but is not limited to:
30+
31+
* The API is initialized in `attributes/default.rb`
32+
* The API is
33+
[runtime-safe](https://github.com/facebook/chef-utils/blob/main/Compile-Time-Run-Time.md)
34+
* The API, wherever possible, owns entire configuration 'systems' instead of
35+
'settings' (ala "all sysctls" instead of "a single sysctl") to allow for
36+
automatic cleanup (see point number 2 under [APIs](../README.md#APIs))
37+
38+
### Other Requirements
39+
40+
The format of your `README.md` is up to you, but it **must** reference this
41+
repo, and **should** mention the Philosophy doc and this repos README doc. This
42+
repo includes a [sample README.md](samples/README.md) for you to start with.
43+
44+
We **highly** recommend your license be Apache 2.0 to match the rest of the
45+
Chef ecosystem, however, we **require** it be compatible with Apache 2.0.
46+
47+
How you choose to handle CLA/Copyright is up to you, but we recommend the
48+
[Developer Certificate of
49+
Origin](https://www.chef.io/blog/introducing-developer-certificate-of-origin)
50+
approach and the [DCO Action](https://github.com/tim-actions/dco) to check it.
51+
52+
Your repository **must** use our [reusable Kitchen
53+
workflow](../../.github/workflows/reusable-kitchen-tests.yml) and [reusable
54+
Lint/Unit workflow](.github/workflows/reusable-ci.yml) (see [docs
55+
below](#reusable-github-actions-workflows)).
56+
57+
Setting up your Repo
58+
--------------------
59+
60+
* Symlink (or copy, if you prefer)
61+
[run_upstream_script](../scripts/run_upstream_script) from this repo into
62+
your repo's `scripts/` directory.
63+
* Copy the [sample README.md](samples/README.md) to your repo, modify to taste.
64+
You will need to replace `YOUR_ORG`, `YOUR_REPO`, and `YOUR_TITLE`, at a
65+
minimum.
66+
* Copy the [sample ci.yml](samples/workflows/ci.yml) and [sample
67+
kitchen.yml](samples/workflows/kitchen.yml) to your repo's
68+
`.github/workflows` directory, and modify to taste
69+
* If you want to use DCO, copy [sample dco.yml](samples/workflows/dco.yml) to
70+
your repo's `.github/workflows` directory.
71+
* Put your cookbooks in your `cookbooks/` directory
72+
* Popluate your `LICENSE` and `CONTRIBUTING.md` file
73+
74+
Once that repo is up and working, create a PR in this repo to add your repo to
75+
76+
* [UNIVERSE.md](../UNIVERSE.md)
77+
* [repo_stats_config.rb](../community_meetings/repo_stats_config.rb)
78+
79+
Testing Locally
80+
---------------
81+
82+
We provide a [run_upstream_script](../scripts/run_upstream_script) script which
83+
will do the work of properly running the upstream scripts for your repo. It
84+
basically figures out how to run whatever script you want, takes the arguements
85+
you pass it, changes directory into your checkout of this upstream repo so that
86+
it has the relevant configs, plugins, etc., and modifies or adds any arguements
87+
to point it back to what you called it with.
88+
89+
Any filename args should be passed **after** a `--`
90+
91+
So for example if you run, from the root of your directory:
92+
93+
```shell
94+
./scripts/run_upstream_script run_mdl
95+
```
96+
97+
It'll run:
98+
99+
```shell
100+
cd ../chef-cookbooks
101+
./scripts/run_mdl $path_to_your_repo
102+
```
103+
104+
Or, if you run this from within `cookbooks/zz_foo`:
105+
106+
```shell
107+
../../scripts/run_upstream_script run_chefspec -- .
108+
```
109+
110+
Then it will run:
111+
112+
```shell
113+
cd ../../../chef-cookbooks
114+
./scripts/run_chefspec $path_to_your_repo/cookbooks/zz_foo/.
115+
```
116+
117+
If no file-like arguments are passed, it'll pass the root directory of your
118+
repo as the arguement.
119+
120+
Since the script aims to be completely transparent, it does not, itself,
121+
accept any arguements, but you may specify DEBUG=1 in the environment to
122+
get debugging information out of it:
123+
124+
```shell
125+
DEBUG=1 ./scripts/run_upstream_script ...
126+
```
127+
128+
Reusable GitHub Actions Workflows
129+
---------------------------------
130+
131+
### Kitchen
132+
133+
The reusable kitchen workfow is required and takes several inputs:
134+
135+
* `universe` - For universe repos, you must set this to `true` (it defaults to
136+
false, for this repo).
137+
* `suite` - By default, this is `default`, but if you want to change the
138+
Kitchen suite that runs (to change the runlist, mostly), you can change this
139+
here.
140+
* `additional_os_list` - The main OSes that Meta's cookbooks are tested on is a
141+
requirement for all Universe repos, but you may add additional ones here in
142+
the form of a JSON string array, e.g. `'["some-os", "some-other-os"]'`.
143+
* `kitchen_local_yaml` - An optional filename to pass in with additional
144+
kitchen configs. This is required both if you specify additional OSes, but
145+
also if you specify a different suite.
146+
147+
The minimal job description would be:
148+
149+
```yaml
150+
kitchen:
151+
uses: facebook/chef-cookbooks/.github/workflows/reusable-kitchen-tests.yml@main
152+
with:
153+
universe: true
154+
```
155+
156+
But let's say you wanted a different runlist. You could create a `.kitchen.local.yaml` with:
157+
158+
```yaml
159+
suites:
160+
- name: local
161+
run_list:
162+
- recipe[my_base_recipe]
163+
```
164+
165+
And then pass in this under `with`:
166+
167+
```yaml
168+
suite: local
169+
kitchen_local_yaml: .kitchen.local.yaml
170+
```
171+
172+
Similarly defining additional OSes, will require defining them under
173+
`platforms` in your local kitchen file when passing them into
174+
`additional_os_list`.
175+
176+
### CI (aka lint and unit testing)
177+
178+
The reusable CI workflow is required and takes several inputs:
179+
180+
* `universe` - For universe repos, you must set this to `true` (it defaults to
181+
false, for this repo).
182+
* `additional_ruby_versions` - The main Ruby versions that Meta's cookbooks are
183+
tested on is a requirement for all Universe repos, but you may add additional
184+
ones here in the form of a JSON string array, e.g. `'["3.4", "3.5"]'`.
185+
186+
The minimal job description would be:
187+
188+
```yaml
189+
ci:
190+
uses: facebook/chef-cookbooks/.github/workflows/reusable-ci.yml@main
191+
with:
192+
universe: true
193+
```

‎docs/samples/README.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
YOUR_REPO_NAME
2+
========================
3+
4+
[![Continuous Integration](https://github.com/YOUR_ORG/YOUR_REPO/actions/workflows/ci.yml/badge.svg)](https://github.com/YOUR_ORG/YOUR_REPO/actions/workflows/ci.yml)
5+
[![Kitchen Tests](https://github.com/YOUR_ORG/YOUR_REPO/actions/workflows/kitchen.yml/badge.svg)](https://github.com/YOUR_ORG/YOUR_REPO/actions/workflows/kitchen.yml)
6+
7+
This repo contains attribute-driven-API cookbooks that follow the [Meta/FB
8+
API](https://github.com/facebook/chef-cookbooks) model, but are not maintained
9+
by Meta.
10+
11+
Required reading:
12+
* [Meta's Chef Philosophy](https://github.com/facebook/chef-utils/blob/main/Philosophy.md)
13+
* [Meta's Chef Cookbook Suite README](https://github.com/facebook/chef-cookbooks/blob/main/README.md)
14+
15+
License
16+
-------
17+
See the LICENSE file in this directory.

‎docs/samples/workflows/ci.yml‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
name: Continuous Integration
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
8+
jobs:
9+
ci:
10+
uses: facebook/chef-cookbooks/.github/workflows/reusable-ci.yml@main
11+
with:
12+
universe: true
13+
# you may also specify additional_ruby_versions as a JSON string array

‎docs/samples/workflows/dco.yml‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
name: DCO Check
2+
on: [pull_request]
3+
4+
jobs:
5+
dco_check_job:
6+
runs-on: ubuntu-latest
7+
name: DCO Check
8+
steps:
9+
- name: Get PR Commits
10+
uses: tim-actions/get-pr-commits@master
11+
id: 'get-pr-commits'
12+
with:
13+
token: ${{ secrets.GITHUB_TOKEN }}
14+
- name: DCO Check
15+
uses: tim-actions/dco@master
16+
with:
17+
commits: ${{ steps.get-pr-commits.outputs.commits }}

‎docs/samples/workflows/kitchen.yml‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
name: Kitchen Tests
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
8+
jobs:
9+
kitchen:
10+
strategy:
11+
fail-fast: false
12+
uses: facebook/chef-cookbooks/.github/workflows/reusable-kitchen-tests.yml@main
13+
secrets: inherit
14+
with:
15+
universe: true
16+
# You may also specify alternative `suite` (string), as well as
17+
# `additional_os_list` (JSON string array).
18+
# Biwth will require a local kitchen file passed in via
19+
# `kitchen_local_yaml` (string).

‎scripts/run_upstream_script‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
#!/bin/bash
2+
#
3+
# vim: syntax=ruby:expandtab:shiftwidth=2:softtabstop=2:tabstop=2
4+
#
5+
# Copyright (c) 2025-present, Phil Dibowitz
6+
# Copyright (c) 2025-present, Facebook, Inc.
7+
# All rights reserved.
8+
#
9+
# Licensed under the Apache License, Version 2.0 (the "License");
10+
# you may not use this file except in compliance with the License.
11+
# You may obtain a copy of the License at
12+
#
13+
# http://www.apache.org/licenses/LICENSE-2.0
14+
#
15+
# Unless required by applicable law or agreed to in writing, software
16+
# distributed under the License is distributed on an "AS IS" BASIS,
17+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
18+
# See the License for the specific language governing permissions and
19+
# limitations under the License.
20+
21+
# This script is for Universe repos. Do not run from this repo and expect
22+
# it to do anything sensible.
23+
#
24+
# This script does the work of running scripts from this repo intelligently
25+
# for other repos.
26+
#
27+
# Run with DEBUG=1 in the env to get debug info
28+
29+
set -eu
30+
31+
: "${DEBUG:=0}"
32+
33+
debug() {
34+
if [ "$DEBUG" -eq 1 ]; then
35+
echo "DEBUG: $*" >&2
36+
fi
37+
}
38+
39+
script="$1"
40+
shift
41+
42+
base_dir=$(git rev-parse --show-toplevel)
43+
upstream_dir="$base_dir/../chef-cookbooks"
44+
45+
args_after_double_dash=()
46+
args_before_double_dash=()
47+
found_double_dash=0
48+
49+
for arg in "$@"; do
50+
if [[ $found_double_dash -eq 1 ]]; then
51+
if [[ "$arg" =~ ^/ ]]; then
52+
args_after_double_dash+=("$arg")
53+
else
54+
args_after_double_dash+=("$PWD/$arg")
55+
fi
56+
elif [[ "$arg" == "--" ]]; then
57+
found_double_dash=1
58+
else
59+
args_before_double_dash+=("$arg")
60+
fi
61+
done
62+
63+
if [[ $found_double_dash -eq 0 ]]; then
64+
args_after_double_dash+=("$base_dir")
65+
fi
66+
67+
# special case... - run_cookstyle requires
68+
# -C for sane external usage
69+
if [[ "$script" == 'run_cookstyle' ]]; then
70+
args_before_double_dash+=("-C")
71+
fi
72+
73+
echo "Running $script on" "${args_after_double_dash[@]}"
74+
cmd=(
75+
"./scripts/$script"
76+
"${args_before_double_dash[@]}"
77+
"${args_after_double_dash[@]}"
78+
)
79+
debug "Command is (from $upstream_dir)" "${cmd[@]}"
80+
cd "$upstream_dir"
81+
exec "${cmd[@]}"

0 commit comments

Comments
 (0)