Skip to content

Commit 1bdce5d

Browse files
JoshuaKGoldbergmichaelfaithlishaduck
authored
docs: added a 'Project' site section for contributing and maintenance (#2306)
## PR Checklist - [x] Addresses an existing open issue: fixes #000 - [x] That issue was marked as [`status: accepting prs`](https://github.com/flint-fyi/flint/issues?q=is%3Aopen+is%3Aissue+label%3A%22status%3A+accepting+prs%22) - [x] Steps in [CONTRIBUTING.md](https://github.com/flint-fyi/flint/blob/main/.github/CONTRIBUTING.md) were taken ## Overview Moves content from the following `.github/*.md` pages into the site to be more discoverable: * `.github/CODE_OF_CONDUCT.md` -> `/project/code-of-conduct` * `.github/Contributing.md` -> `/project/contributing` * `.github/Development.md` -> `/project/development` Adds a new `/project/maintenance` page that summarizes #1242: * Issues are `status: in discussion` until they're in `status: accepting prs` * PRs should get approval from >=1 member of each group (Committer, Maintainer) * For both, the waiting periods are: none for trivial size; 5 for very big; 2 otherwise This intentionally leaves me (Project Lead) out of requirements for anything, as things shouldn't be blocked on me at all. Also adds an FAQ about getting involved that points at Contributing. Is there anything else we should add in? ❤️‍🔥 --------- Co-authored-by: michael faith <[email protected]> Co-authored-by: Eli <[email protected]>
1 parent efe6df5 commit 1bdce5d

File tree

13 files changed

+452
-324
lines changed

13 files changed

+452
-324
lines changed

.changeset/giant-times-repair.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,4 @@
22
"@flint.fyi/core": minor
33
---
44

5-
factor in plugin IDs for comment directives
5+
Factor in plugin IDs for comment directives.

.github/CODE_OF_CONDUCT.md

Lines changed: 3 additions & 129 deletions
Original file line numberDiff line numberDiff line change
@@ -1,131 +1,5 @@
1-
# Contributor Covenant Code of Conduct
1+
# Code of Conduct
22

3-
## Our Pledge
3+
Thanks for your interest in contributing to `flint`! ❤️‍🔥
44

5-
We as members, contributors, and leaders pledge to make participation in our
6-
community a harassment-free experience for everyone, regardless of age, body
7-
size, visible or invisible disability, ethnicity, sex characteristics, gender
8-
identity and expression, level of experience, education, socio-economic status,
9-
nationality, personal appearance, race, caste, color, religion, or sexual
10-
identity and orientation.
11-
12-
We pledge to act and interact in ways that contribute to an open, welcoming,
13-
diverse, inclusive, and healthy community.
14-
15-
## Our Standards
16-
17-
Examples of behavior that contributes to a positive environment for our
18-
community include:
19-
20-
- Demonstrating empathy and kindness toward other people
21-
- Being respectful of differing opinions, viewpoints, and experiences
22-
- Giving and gracefully accepting constructive feedback
23-
- Accepting responsibility and apologizing to those affected by our mistakes,
24-
and learning from the experience
25-
- Focusing on what is best not just for us as individuals, but for the overall
26-
community
27-
28-
Examples of unacceptable behavior include:
29-
30-
- The use of sexualized language or imagery, and sexual attention or advances of
31-
any kind
32-
- Trolling, insulting or derogatory comments, and personal or political attacks
33-
- Public or private harassment
34-
- Publishing others' private information, such as a physical or email address,
35-
without their explicit permission
36-
- Other conduct which could reasonably be considered inappropriate in a
37-
professional setting
38-
39-
## Enforcement Responsibilities
40-
41-
Community leaders are responsible for clarifying and enforcing our standards of
42-
acceptable behavior and will take appropriate and fair corrective action in
43-
response to any behavior that they deem inappropriate, threatening, offensive,
44-
or harmful.
45-
46-
Community leaders have the right and responsibility to remove, edit, or reject
47-
comments, commits, code, wiki edits, issues, and other contributions that are
48-
not aligned to this Code of Conduct, and will communicate reasons for moderation
49-
decisions when appropriate.
50-
51-
## Scope
52-
53-
This Code of Conduct applies within all community spaces, and also applies when
54-
an individual is officially representing the community in public spaces.
55-
Examples of representing our community include using an official e-mail address,
56-
posting via an official social media account, or acting as an appointed
57-
representative at an online or offline event.
58-
59-
## Enforcement
60-
61-
Instances of abusive, harassing, or otherwise unacceptable behavior may be
62-
reported to the community leaders responsible for enforcement at
63-
64-
All complaints will be reviewed and investigated promptly and fairly.
65-
66-
All community leaders are obligated to respect the privacy and security of the
67-
reporter of any incident.
68-
69-
## Enforcement Guidelines
70-
71-
Community leaders will follow these Community Impact Guidelines in determining
72-
the consequences for any action they deem in violation of this Code of Conduct:
73-
74-
### 1. Correction
75-
76-
**Community Impact**: Use of inappropriate language or other behavior deemed
77-
unprofessional or unwelcome in the community.
78-
79-
**Consequence**: A private, written warning from community leaders, providing
80-
clarity around the nature of the violation and an explanation of why the
81-
behavior was inappropriate.
82-
A public apology may be requested.
83-
84-
### 2. Warning
85-
86-
**Community Impact**: A violation through a single incident or series of
87-
actions.
88-
89-
**Consequence**: A warning with consequences for continued behavior.
90-
No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time.
91-
This includes avoiding interactions in community spaces as well as external channels like social media.
92-
Violating these terms may lead to a temporary or permanent ban.
93-
94-
### 3. Temporary Ban
95-
96-
**Community Impact**: A serious violation of community standards, including
97-
sustained inappropriate behavior.
98-
99-
**Consequence**: A temporary ban from any sort of interaction or public
100-
communication with the community for a specified period of time.
101-
No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period.
102-
Violating these terms may lead to a permanent ban.
103-
104-
### 4. Permanent Ban
105-
106-
**Community Impact**: Demonstrating a pattern of violation of community
107-
standards, including sustained inappropriate behavior, harassment of an
108-
individual, or aggression toward or disparagement of classes of individuals.
109-
110-
**Consequence**: A permanent ban from any sort of public interaction within the
111-
community.
112-
113-
## Attribution
114-
115-
This Code of Conduct is adapted from the [Contributor Covenant][homepage],
116-
version 2.1, available at
117-
[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
118-
119-
Community Impact Guidelines were inspired by
120-
[Mozilla's code of conduct enforcement ladder][mozilla coc].
121-
122-
For answers to common questions about this code of conduct, see the FAQ at
123-
[https://www.contributor-covenant.org/faq][faq].
124-
Translations are available at
125-
[https://www.contributor-covenant.org/translations][translations].
126-
127-
[homepage]: https://www.contributor-covenant.org
128-
[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
129-
[mozilla coc]: https://github.com/mozilla/diversity
130-
[faq]: https://www.contributor-covenant.org/faq
131-
[translations]: https://www.contributor-covenant.org/translations
5+
See **[flint.fyi/project/code-of-conduct](https://flint.fyi/project/code-of-conduct)** for our code of conduct.

.github/CONTRIBUTING.md

Lines changed: 1 addition & 98 deletions
Original file line numberDiff line numberDiff line change
@@ -2,101 +2,4 @@
22

33
Thanks for your interest in contributing to `flint`! ❤️‍🔥
44

5-
> After this page, see [DEVELOPMENT.md](./DEVELOPMENT.md) for local development instructions.
6-
7-
## Code of Conduct
8-
9-
This project contains a [Contributor Covenant code of conduct](./CODE_OF_CONDUCT.md) all contributors are expected to follow.
10-
11-
## Reporting Issues
12-
13-
Please do [report an issue on the issue tracker](https://github.com/flint-fyi/flint/issues/new/choose) if there's any bugfix, documentation improvement, or general enhancement you'd like to see in the repository! Please fully fill out all required fields in the most appropriate issue form.
14-
15-
## Sending Contributions
16-
17-
Sending your own changes as contribution is always appreciated!
18-
There are two steps involved:
19-
20-
1. [Finding an Issue](#finding-an-issue)
21-
2. [Sending a Pull Request](#sending-a-pull-request)
22-
23-
### Finding an Issue
24-
25-
With the exception of very small typos, all changes to this repository generally need to correspond to an [unassigned open issue marked as `status: accepting prs` and not `ai assigned` on the issue tracker](https://github.com/flint-fyi/flint/issues?q=is%3Aissue%20is%3Aopen%20label%3A%22status%3A%20accepting%20prs%22%20-label%3A%22ai%20assigned%22%20no%3Aassignee).
26-
If this is your first time contributing, consider searching for [unassigned issues that also have the `good first issue` label](https://github.com/flint-fyi/flint/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22+label%3A%22status%3A+accepting+prs%22+no%3Aassignee+).
27-
If the issue you'd like to fix isn't found on the issue, see [Reporting Issues](#reporting-issues) for filing your own (please do!).
28-
29-
#### Issue Claiming
30-
31-
We don't use any kind of issue claiming system.
32-
We've found in the past that they result in accidental ["licked cookie"](https://devblogs.microsoft.com/oldnewthing/20091201-00/?p=15843) situations where contributors claim an issue but run out of time or energy trying before sending a PR.
33-
34-
If an unassigned issue has been marked as `status: accepting prs` and an open PR does not exist, feel free to send a PR.
35-
Please don't post comments asking for permission or stating you will work on an issue.
36-
37-
### Sending a Pull Request
38-
39-
Once you've identified an open issue accepting PRs that doesn't yet have a PR sent, you're free to send a pull request.
40-
Be sure to fill out the pull request template's requested information -- otherwise your PR will likely be closed.
41-
42-
PRs are also expected to have a title that adheres to [conventional commits](https://www.conventionalcommits.org/en/v1.0.0).
43-
Only PR titles need to be in that format, not individual commits.
44-
Don't worry if you get this wrong: you can always change the PR title after sending it.
45-
Check [previously merged PRs](https://github.com/flint-fyi/flint/pulls?q=is%3Apr+is%3Amerged+-label%3Adependencies+) for reference.
46-
47-
Finally, if your PR includes any user-facing changes, run `pnpm changeset` to [add a proper changeset](https://github.com/changesets/changesets/blob/main/docs/adding-a-changeset.md).
48-
This should _not_ use traditional conventional commit syntax, and should instead reflect what you would want the user to see in the changelog.
49-
For example, everything _after_ the initial colon in a commit title would be sufficient.
50-
This will allow our release automation to version packages appropriately when the next release happens.
51-
52-
#### Draft PRs
53-
54-
If you don't think your PR is ready for review, [set it as a draft](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-stage-of-a-pull-request#converting-a-pull-request-to-a-draft).
55-
Draft PRs won't be reviewed.
56-
57-
#### Granular PRs
58-
59-
Please keep pull requests single-purpose: in other words, don't attempt to solve multiple unrelated problems in one pull request.
60-
Send one PR per area of concern.
61-
Multi-purpose pull requests are harder and slower to review, block all changes from being merged until the whole pull request is reviewed, and are difficult to name well with semantic PR titles.
62-
63-
#### Pull Request Reviews
64-
65-
When a PR is not in draft, it's considered ready for review.
66-
Please don't manually `@` tag anybody to request review.
67-
A maintainer will look at it when they're next able to.
68-
69-
PRs should have passing [GitHub status checks](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/about-status-checks) before review is requested (unless there are explicit questions asked in the PR about any failures).
70-
71-
#### Asking Questions
72-
73-
If you need help and/or have a question, posting a comment in the PR is a great way to do so.
74-
There's no need to tag anybody individually.
75-
One of us will drop by and help when we can.
76-
77-
Please post comments as [line comments](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/commenting-on-a-pull-request#adding-line-comments-to-a-pull-request) when possible, so that they can be threaded.
78-
You can [resolve conversations](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/commenting-on-a-pull-request#resolving-conversations) on your own when you feel they're resolved - no need to comment explicitly and/or wait for a maintainer.
79-
80-
#### Requested Changes
81-
82-
After a maintainer reviews your PR, they may request changes on it.
83-
Once you've made those changes, [re-request review on GitHub](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/about-pull-request-reviews#re-requesting-a-review).
84-
85-
Please try not to force-push commits to PRs that have already been reviewed.
86-
Doing so makes it harder to review the changes.
87-
We squash merge all commits so there's no need to try to preserve Git history within a PR branch.
88-
89-
Once you've addressed all our feedback by making code changes and/or started a followup discussion, [re-request review](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/about-pull-request-reviews#re-requesting-a-review) from each maintainer whose feedback you addressed.
90-
91-
Once all feedback is addressed and the PR is approved, we'll ensure the branch is up to date with `main` and merge it for you.
92-
93-
#### Post-Merge Recognition
94-
95-
Once your PR is merged, if you haven't yet been added to the [_Contributors_ table in the README.md](../README.md#contributors) for its [type of contribution](https://allcontributors.org/docs/en/emoji-key "Allcontributors emoji key"), you should be soon.
96-
Please do ping the maintainer who merged your PR if that doesn't happen within 24 hours - it was likely an oversight on our end!
97-
98-
## Emojis & Appreciation
99-
100-
If you made it all the way to the end, bravo dear user, we love you.
101-
Please include an emoji in the bottom of your issues and PRs to signal to us that you did in fact read this file and are trying to conform to it as best as possible.
102-
❤️‍🔥 is a good starter if you're not sure which to use.
5+
See **[flint.fyi/project/contributing](https://flint.fyi/project/contributing)** for how to work with the Flint project.

.github/DEVELOPMENT.md

Lines changed: 2 additions & 94 deletions
Original file line numberDiff line numberDiff line change
@@ -1,97 +1,5 @@
11
# Development
22

3-
After [forking the repo from GitHub](https://help.github.com/articles/fork-a-repo) and [installing pnpm](https://pnpm.io/installation):
3+
Thanks for your interest in contributing to `flint`! ❤️‍🔥
44

5-
```shell
6-
git clone https://github.com/(your-name-here)/flint
7-
cd flint
8-
pnpm install
9-
```
10-
11-
> This repository includes a list of suggested VS Code extensions.
12-
> It's a good idea to use [VS Code](https://code.visualstudio.com) and accept its suggestion to install them, as they'll help with development.
13-
14-
## Building
15-
16-
Run TypeScript's builder mode locally to build source files from `src/` into output files in `lib/`:
17-
18-
```shell
19-
pnpm build
20-
```
21-
22-
Add `--watch` to run the builder in a watch mode that continuously recreates `lib/` as you save files:
23-
24-
```shell
25-
pnpm build --watch
26-
```
27-
28-
## Formatting
29-
30-
[Prettier](https://prettier.io) is used to format code.
31-
It should be applied automatically when you save files in VS Code or make a Git commit.
32-
33-
To manually reformat all files, you can run:
34-
35-
```shell
36-
pnpm format --write
37-
```
38-
39-
## Linting
40-
41-
This package includes several forms of linting to enforce consistent code quality and styling.
42-
Each should be shown in VS Code, and can be run manually on the command-line:
43-
44-
- `pnpm lint` ([ESLint](https://eslint.org) with [typescript-eslint](https://typescript-eslint.io)): Lints JavaScript and TypeScript source files
45-
- `pnpm lint:knip` ([knip](https://github.com/webpro/knip)): Detects unused files, dependencies, and code exports
46-
- `pnpm lint:packages` ([pnpm dedupe --check](https://pnpm.io/cli/dedupe)): Checks for unnecessarily duplicated packages in the `pnpm-lock.yaml` file
47-
48-
Read the individual documentation for each linter to understand how it can be configured and used best.
49-
50-
For example, ESLint can be run with `--fix` to auto-fix some lint rule complaints:
51-
52-
```shell
53-
pnpm run lint --fix
54-
```
55-
56-
Note that you'll need to run `pnpm build` before `pnpm lint` so that lint rules which check the file system can pick up on any built files.
57-
58-
## Testing
59-
60-
[Vitest](https://vitest.dev) is used for tests.
61-
You can run it locally on the command-line:
62-
63-
```shell
64-
pnpm run test
65-
```
66-
67-
Note that [console-fail-test](https://github.com/JoshuaKGoldberg/console-fail-test) is enabled for all test runs.
68-
Calls to `console.log`, `console.warn`, and other console methods will cause a test to fail.
69-
70-
### Debugging Tests
71-
72-
This repository includes a [VS Code launch configuration](https://code.visualstudio.com/docs/editor/debugging) for debugging unit tests.
73-
To launch it, open a test file, then run _Debug Current Test File_ from the VS Code Debug panel (or press F5).
74-
75-
## Common Contributing Tasks
76-
77-
The following sections detail common tasks you may want to perform when contributing to Flint.
78-
79-
### Writing a New Rule
80-
81-
> [!TIP]
82-
> Search for an existing rule with a similar purpose to see all the places it's referenced.
83-
84-
To add a new rule, `{ruleName}` to an existing Flint plugin `{plugin}`:
85-
86-
1. Create the following files, copying contents from an existing rule as a starting point:
87-
- `packages/{plugin}/src/rules/{ruleName}.ts`
88-
- `packages/{plugin}/src/rules/{ruleName}.test.ts`
89-
- `packages/site/src/content/docs/rules/{plugin}/{ruleName}.mdx`
90-
2. Updating existing files that reference rules:
91-
- `packages/{plugin}/src/plugin.ts`: adding the rule in alphabetical order to `rules`
92-
- `packages/comparisons/src/data.json`: marking the rule as `"status": "implemented"`
93-
3. Try to follow these best practices when writing the rule's documentation and tests:
94-
- In documentation, see the sections present in other rules and fill them out
95-
- In _Further Reading_ documentation, find at least one first-party source such as MDN
96-
- _When Not To Use It_ should not say to always use the rule; instead, think of at least one legitimate reason - even if it's legacy runtimes
97-
- In tests, use as straightforward code snippets as possible, preferring generic names like `value` over references like `foo`/`bar`
5+
See **[flint.fyi/project/development](https://flint.fyi/project/development)** for technical steps around how to work on the Flint project codebase.

cspell.json

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,7 @@
4141
"backreferenced",
4242
"barrymichaeldoyle",
4343
"bday",
44+
"BDFL",
4445
"bradzacher",
4546
"codemod",
4647
"contentinfo",
@@ -73,6 +74,7 @@
7374
"oxendict",
7475
"Oxlint",
7576
"prefault",
77+
"rearchitectures",
7678
"recurser",
7779
"roletype",
7880
"ronami",

packages/site/astro.config.ts

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,24 @@ export default defineConfig({
4343
{ label: "Configuration", link: "configuration" },
4444
{ label: "Glossary", link: "glossary" },
4545
{ label: "FAQs", link: "faqs" },
46-
{ label: "Team", link: "team" },
46+
{
47+
collapsed: true,
48+
items: [
49+
{
50+
label: "Code of Conduct",
51+
link: "project/code-of-conduct",
52+
},
53+
{ label: "Contributing", link: "project/contributing" },
54+
{
55+
label: "Contributing with AI",
56+
link: "project/contributing-with-ai",
57+
},
58+
{ label: "Development", link: "project/development" },
59+
{ label: "Maintenance", link: "project/maintenance" },
60+
{ label: "Team", link: "project/team" },
61+
],
62+
label: "Project",
63+
},
4764
],
4865
label: "About",
4966
link: "about",
@@ -128,6 +145,7 @@ export default defineConfig({
128145
},
129146
redirects: {
130147
"/discord": "https://discord.gg/cFK3RAUDhy",
148+
"/team": "/project/team",
131149
},
132150
site: "https://flint.fyi",
133151
vite: {

0 commit comments

Comments
 (0)