Skip to content

Commit 9688d22

Browse files
oddgrdgithub-actions
oddgrd
and
github-actions
authored
ci: add workflow to fetch contrib docs nightly (#78)
* ci: add workflow to fetch contrib docs * actions: update contrib * feat: convert doc titles to frontmatter in CI also start implementing the contrib section, but it might need a new layout * ci: fix path to docs * actions: update contrib * ci: split up commands * refactor: delete old docs with underscores * ci: convert readme to index * actions: update contrib * feat: implement the contrib section in the website * ci: fix svg link * ci: revert svg link fix * ci: test out the pull request action * doc: update contrib docs * ci: update permissions * feat: lowercase internal links * doc: update contrib docs * ci: lowercase link names, comment commands * ci: add back contents write permission * ci: don't lowercase MSRV, it's not used as a link this is not ideal, but the script to lowercase links could be changed to allow MSRV name to be capitalized and links to be lowercased should we want to use MSRV as a link * doc: update contrib docs * ci: add contributing.md to the contrib docs * doc: update contrib docs * feat: add contributing to _data Co-authored-by: github-actions <github-actions@github.com>
1 parent c9eb0db commit 9688d22

File tree

20 files changed

+1321
-1
lines changed

20 files changed

+1321
-1
lines changed

‎.github/workflows/CI.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,8 @@ on:
44
push:
55
branches:
66
- master
7+
paths-ignore:
8+
- "_contrib/**"
79

810
env:
911
RUST_BACKTRACE: 1

‎.github/workflows/contrib.yml‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
name: contrib
2+
on:
3+
schedule:
4+
- cron: '15 3 * * *'
5+
workflow_dispatch:
6+
7+
permissions:
8+
contents: write # to update _contrib
9+
pull-requests: write # to send the updated _contrib PRs
10+
11+
jobs:
12+
update-contrib:
13+
name: Update _contrib
14+
runs-on: ubuntu-latest
15+
16+
steps:
17+
- name: Checkout website
18+
uses: actions/checkout@v3
19+
with:
20+
persist-credentials: false
21+
22+
- name: Checkout hyper
23+
uses: actions/checkout@v3
24+
with:
25+
persist-credentials: false
26+
repository: hyperium/hyper
27+
path: hyper
28+
29+
- name: Copy CONTRIBUTING.md into docs
30+
run: |
31+
sed -i -e 's|./docs/||g' hyper/CONTRIBUTING.md
32+
cp -a hyper/CONTRIBUTING.md hyper/docs
33+
34+
# Insert frontmatter borders, replace markdown header with
35+
# frontmatter title and insert layout: guide
36+
- name: Convert doc titles to frontmatter
37+
run: |
38+
for f in hyper/docs/*.md; do
39+
sed -i -e '1i ---' \
40+
-e '1s/#/title:/' \
41+
-e '2i layout: guide' \
42+
-e '2i ---' $f;
43+
done
44+
45+
# Use the hyper docs readme as the index page of contrib,
46+
# and insert permalink: /contrib/ in the frontmatter
47+
- name: Convert readme to index
48+
run: |
49+
sed -i -e '4i permalink: /contrib/' hyper/docs/README.md
50+
mv hyper/docs/README.md hyper/docs/index.md
51+
52+
# Lowercase the internal links so they will correctly point to
53+
# the lowercased filenames.
54+
- name: Lowercase internal links
55+
run: |
56+
for filename in hyper/docs/*.md; do
57+
# cut `.md` from the filename before search and replace
58+
filename=${filename::-3};
59+
60+
for file in hyper/docs/*.md; do
61+
# don't lowercase MSRV
62+
if [[ "${filename##*/}" == 'MSRV' ]]; then
63+
continue
64+
fi
65+
66+
# match instances of only the filename, not including
67+
# the parent path, and convert them to lowercase
68+
sed -i -e "s|${filename##*/}|\L\0|g" $file;
69+
done
70+
done
71+
72+
- name: Lowercase filenames and replace underscores
73+
run: |
74+
for f in hyper/docs/*; do
75+
mv -vn "$f" "$(echo "$f" | tr '[:upper:]' '[:lower:]' | tr '_' '-')";
76+
done
77+
78+
- name: Copy docs to contrib
79+
run: |
80+
mkdir -p _contrib
81+
cp -a hyper/docs/. _contrib/
82+
83+
- uses: gr2m/create-or-update-pull-request-action@v1
84+
env:
85+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
86+
with:
87+
author: github-actions <github-actions@github.com>
88+
branch: actions/update-contrib
89+
title: 'doc: update contrib docs'
90+
body: >
91+
The _contrib docs are likely out of date. This is an automatically
92+
generated PR by the `contrib.yml` GitHub workflow, which clones the docs
93+
from the main repo, implements the changes in _contrib then submits a new
94+
PR or updates an existing PR.
95+
commit-message: 'doc: update contrib docs'
96+
path: _contrib/
97+

‎_config.yml‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,12 +11,17 @@ defaults:
1111
values:
1212
layout: "guide"
1313
-
14-
1514
scope:
1615
path: "_stable/"
1716
type: "guides"
1817
values:
1918
layout: "guide"
19+
-
20+
scope:
21+
path: "_contrib/"
22+
type: "guides"
23+
values:
24+
layout: "guide"
2025

2126

2227
collections:
@@ -29,6 +34,9 @@ collections:
2934
posts:
3035
permalink: /blog/:year/:month/:day/:title/
3136
output: true
37+
contrib:
38+
permalink: /contrib/:path/
39+
output: true
3240

3341
# Build settings
3442
markdown: kramdown

‎_contrib/code-of-conduct.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
---
2+
title: Code of Conduct
3+
layout: guide
4+
---
5+
6+
## Be Kind
7+
8+
- Don't be mean.
9+
- Insulting anyone is prohibited.
10+
- Harassment of any kind is prohibited.
11+
- If another person feels uncomfortable with your remarks, stop it.
12+
- If a moderator deems your comment or conduct as inappropriate, stop it.
13+
- Disagreeing is fine, but keep it to technical arguments. Never attack the person.
14+
- Give the benefit of the doubt. Assume good intentions.
15+
- Show empathy. There are 3 interpretations to any message: what we thought, what we said, and what they understand.
16+
- This does mean we exclude people who are not kind. We are happy to make that sacrifice.
17+
18+
## Or Else
19+
20+
- Violations of the Code of Conduct will result in 1 warning.
21+
- If the violation is major, a moderator may just ban immediately.
22+
- If a warning has already been given, a moderator will ban the offender.
23+
- There is no process for appealing a ban.
24+
- Any violations can be reported to sean@seanmonstar.com.

‎_contrib/commits.md‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
---
2+
title: Git Commit Guidelines
3+
layout: guide
4+
---
5+
6+
We have very precise rules over how our git commit messages can be formatted. This leads to **more
7+
readable messages** that are easy to follow when looking through the **project history**. But also,
8+
we use the git commit messages to **generate the change log**.
9+
10+
## Commit Message Format
11+
Each commit message consists of a **header**, a **body** and a **footer**. The header has a special
12+
format that includes a **type**, a **scope** and a **subject**:
13+
14+
```
15+
<type>(<scope>): <subject>
16+
<BLANK LINE>
17+
<body>
18+
<BLANK LINE>
19+
<footer>
20+
```
21+
22+
Any line of the commit message cannot be longer 100 characters! This allows the message to be easier
23+
to read on github as well as in various git tools.
24+
25+
## Type
26+
Must be one of the following:
27+
28+
* **feat**: A new feature
29+
* **fix**: A bug fix
30+
* **docs**: Documentation only changes
31+
* **style**: Changes that do not affect the meaning of the code (white-space, formatting, missing
32+
semi-colons, etc)
33+
* **refactor**: A code change that neither fixes a bug or adds a feature
34+
* **perf**: A code change that improves performance
35+
* **test**: Adding missing tests
36+
* **chore**: Changes to the build process or auxiliary tools and libraries such as documentation
37+
generation
38+
39+
## Scope
40+
The scope should refer to a module in hyper that is being touched. Examples:
41+
42+
* client
43+
* server
44+
* http1
45+
* http2
46+
* ffi
47+
* upgrade
48+
* examples
49+
50+
## Subject
51+
52+
The subject contains succinct description of the change:
53+
54+
* use the imperative, present tense: "change" not "changed" nor "changes"
55+
* don't capitalize first letter
56+
* no dot (.) at the end
57+
58+
## Body
59+
60+
Just as in the **subject**, use the imperative, present tense: "change" not "changed" nor "changes"
61+
The body should include the motivation for the change and contrast this with previous behavior.
62+
63+
## Footer
64+
65+
The footer should contain any information about **Breaking Changes** and is also the place to
66+
reference GitHub issues that this commit **Closes**.
67+
68+
The last line of commits introducing breaking changes should be in the form `BREAKING CHANGE: <desc>`

‎_contrib/contributing.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
---
2+
title: Contributing to Hyper
3+
layout: guide
4+
---
5+
6+
You want to contribute? You're awesome! Don't know where to start? Check the [list of easy issues](https://github.com/hyperium/hyper/issues?q=is%3Aopen+is%3Aissue+label%3AE-easy).
7+
8+
[easy tag]: https://github.com/hyperium/hyper/issues?q=label%3AE-easy+is%3Aopen
9+
10+
11+
## [Pull Requests](pull_requests.md)
12+
13+
- [Submitting a Pull Request](pull_requests.md#submitting-a-pull-request)
14+
- [Commit Guidelines](commits.md)

‎_contrib/governance.md‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
---
2+
title: Governance
3+
layout: guide
4+
---
5+
6+
## Making decisions
7+
8+
There's two main pieces to the way decisions are made in hyper:
9+
10+
1. A decision-making framework
11+
2. The people who apply it
12+
13+
The people are described [lower down in this document](#roles).
14+
15+
### Decision-making framework
16+
17+
We start with the users. The project wouldn't exist without them, and it exists
18+
in order to enable users to do amazing things with HTTP. We listen to our
19+
users. Some actively contribute their thoughts, but many others we must seek
20+
out to learn about their usage, joys, and headaches. Those insights allow our
21+
experts to determine the best solutions for the users.
22+
23+
We then define a set of [tenets](./tenets.md), which are guiding principles
24+
that can be used to measure aspects of individual decisions. It should be
25+
possible to identify one or more tenets that apply to why a decision is made.
26+
And the set helps us balance which priorities are more important for our users.
27+
28+
We combine the usecases with the tenets to come up with a [vision](./vision.md)
29+
that provides a longer-term plan of what hyper _should_ look like.
30+
31+
Finally, we define a [roadmap](./roadmap.md) that describes what the
32+
short-term, tactical changes to bring hyper closer in line with the vision.
33+
34+
## Roles
35+
36+
These are the roles people can fill when participating in the project. A list
37+
of the people in each role is available in [maintainers](./maintainers.md).
38+
39+
### Contributor
40+
41+
A contributor is anyone who contributes their time to provide value for the
42+
project. This could be in the form of code, documentation, filing issues,
43+
discussing designs, or helping others on the issue tracker or in chat.
44+
45+
All contributors MUST follow the [Code of Conduct][coc].
46+
47+
👋 **New here?** [This could be you!][contrib]
48+
49+
50+
### Triager
51+
52+
Triagers assess issues on the issue tracker. They help make sure the work is
53+
well organized, and are critical for making new issue reporters feeling
54+
welcome.
55+
56+
Responsibilities:
57+
58+
- Adhere to the [Code of Conduct][coc]
59+
- Follow the [triager's guide][triage-guide]
60+
61+
Privileges:
62+
63+
- Can edit, label, and close issues
64+
- Member of the organization
65+
- Can be assigned issues and pull requests
66+
67+
How to become:
68+
69+
- Make a few [contributions][contrib] to the project, to show you can follow
70+
the [Code of Conduct][coc].
71+
- Self-nominate by making a pull request adding yourself to the
72+
[list](./maintainers.md#triagers).
73+
74+
75+
### Collaborator
76+
77+
Collaborators are contributors who have been helping out in a consistent basis.
78+
79+
Responsibilities:
80+
81+
- Be exemplars of the [Code of Conduct][coc]
82+
- Internalize the [vision](./vision.md)
83+
- Reviewing pull requests from other contributors
84+
- Provide feedback on proposed features and design documents
85+
- [Welcome new contributors][triage-guide]
86+
- Answer questions in issues and/or chat
87+
- Mentor contributors to become members
88+
89+
Privileges:
90+
91+
- Can review and merge pull requests
92+
- Can trigger re-runs of CI, and approve CI for first-time contributors
93+
- Can assign issues and pull requests to other organization members
94+
95+
How to become:
96+
97+
- Work at fulfilling the above responsibilities.
98+
- Any collaborator may nominate a contributor who has been around for some time
99+
and is already filling the responsibilities.
100+
- Another collaborator must second the nomination.
101+
- If there are no objections, a maintainer will welcome the new collaborator.
102+
103+
Don't be afraid to ask a collaborator for what you could work on to reach this
104+
goal!
105+
106+
### Maintainer
107+
108+
Maintainers are the project admins. Besides being a collaborator, they take care
109+
of house-keeping duties, help lead the direction, and have the final authority when
110+
required.
111+
112+
[coc]: ./code_of_conduct.md
113+
[contrib]: ../contributing.md
114+
[triage-guide]: ./issues.md#triaging

‎_contrib/index.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
title: Developing hyper
3+
layout: guide
4+
permalink: /contrib/
5+
---
6+
7+
This is a set of documents outline how hyper is developed, how to contribute or get involved, various processes we use, and internal design explanations.

0 commit comments

Comments
 (0)