Skip to content

Commit fd193cf

Browse files
claymcleodclaymcleod
committed
revise: adds the checklist for crate authors
1 parent 751b363 commit fd193cf

File tree

8 files changed

+339
-267
lines changed

8 files changed

+339
-267
lines changed

Diff for: ‎assets/css/main.postcss

+2
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,8 @@
1313
@apply dark:prose-code:bg-slate-800;
1414
}
1515

16+
17+
1618
code::before,
1719
code::after {
1820
content: none !important;

Diff for: ‎components/molecules/docs/CrateCard.vue

+66-4
Original file line numberDiff line numberDiff line change
@@ -8,13 +8,13 @@
88

99
<div class="ml-1 font-normal text-xs font-mono">
1010
<div
11-
class="px-1 py-0.5 rounded-md text-green-900 bg-green-300 border border-green-500"
11+
class="px-1 py-0.5 rounded-md text-green-900 dark:text-green-300 bg-green-300 dark:bg-green-900 border border-green-500"
1212
v-if="kind === Kind.Library"
1313
>
1414
lib
1515
</div>
1616
<div
17-
class="px-1 py-0.5 rounded-md text-purple-900 bg-purple-300 border border-purple-500"
17+
class="px-1 py-0.5 rounded-md text-purple-900 dark:text-purple-300 bg-purple-300 dark:bg-purple-900 border border-purple-500"
1818
v-else-if="kind === Kind.Binary"
1919
>
2020
bin
@@ -24,14 +24,14 @@
2424
<div class="flex gap-x-1.5">
2525
<a
2626
v-if="socials && socials.github"
27-
class="flex items-center justify-center w-7 h-7 bg-gray-100 border border-gray-200 rounded-full"
27+
class="flex items-center justify-center w-7 h-7 bg-gray-100 dark:bg-slate-950 border border-gray-200 rounded-full"
2828
:href="socials.github"
2929
>
3030
<Icon class="w-4 h-4" name="octicon:mark-github-16"></Icon>
3131
</a>
3232
<a
3333
v-if="socials && socials.zulip"
34-
class="flex items-center justify-center w-7 h-7 bg-gray-100 border border-gray-200 rounded-full"
34+
class="flex items-center justify-center w-7 h-7 bg-gray-100 dark:bg-slate-950 border border-gray-200 rounded-full"
3535
href="https://rustseq.zulipchat.com"
3636
:title="`Chat about ${name} in the rust-seq Zulip`"
3737
>
@@ -73,3 +73,65 @@ interface Props {
7373
// Define props with TypeScript
7474
const props = defineProps<Props>();
7575
</script>
76+
77+
<style scope lang="postcss">
78+
.card {
79+
@apply transition;
80+
81+
@apply hover:-translate-y-0.5;
82+
83+
@apply px-6;
84+
@apply py-4;
85+
86+
@apply bg-white;
87+
@apply dark:bg-slate-900;
88+
89+
@apply text-slate-900;
90+
@apply dark:text-slate-50;
91+
92+
@apply border;
93+
@apply border-gray-100;
94+
@apply dark:border-gray-950;
95+
96+
@apply rounded-lg;
97+
@apply shadow-sm;
98+
@apply hover:shadow-md;
99+
100+
@apply text-pretty;
101+
102+
.header {
103+
@apply flex justify-between items-center;
104+
105+
.title {
106+
@apply flex justify-start items-center;
107+
@apply gap-x-1;
108+
109+
@apply font-bold;
110+
font-size: 14px;
111+
@apply text-slate-600;
112+
@apply dark:text-slate-300;
113+
114+
.iconify {
115+
/* Color of the icon. */
116+
@apply bg-slate-600;
117+
@apply dark:bg-slate-300;
118+
}
119+
}
120+
}
121+
122+
.crate {
123+
font-family: "Space Mono";
124+
font-weight: 400;
125+
}
126+
127+
.description {
128+
@apply pt-1;
129+
130+
@apply text-gray-600;
131+
@apply dark:text-gray-300;
132+
@apply text-sm;
133+
134+
@apply text-start;
135+
}
136+
}
137+
</style>

Diff for: ‎content/docs/get-started/2.values.md

+31-31
Original file line numberDiff line numberDiff line change
@@ -27,37 +27,6 @@ provide or mimic functionality that is provided in a library within some other l
2727
will be similarly (or more) performant than the library providing this functionality in
2828
another language.
2929

30-
## Broadly Usable
31-
32-
Crates in the `rust-seq` stack are intended to be broadly used within academic and
33-
industry. As such, they should be **freely-licensed** to enable them to be adopted used
34-
in the broadest variety of contexts. If you do not have a preference on the license, we
35-
recommend you dual license the crate to be used under the [MIT
36-
License](https://opensource.org/license/MIT) or the [Apache-2.0
37-
License](https://opensource.org/license/apache-2-0) at the user's discretion.
38-
39-
Notably, crates _must_ be made accessible under any number of the following licenses (in
40-
alphabetical order):
41-
42-
- [Apache-2.0 License](https://opensource.org/license/apache-2-0)
43-
(learn about this license [here](https://www.tldrlegal.com/license/apache-license-2-0-apache-2-0)),
44-
- [BSD 3-Clause License](https://opensource.org/license/BSD-3-clause)
45-
(learn about this license [here](https://www.tldrlegal.com/license/bsd-3-clause-license-revised)),
46-
- [MIT License](https://opensource.org/license/MIT)
47-
(learn about this license [here](https://www.tldrlegal.com/license/mit-license)),
48-
- or any public domain license (e.g.,
49-
[Unlicense](https://opensource.org/license/unlicense)).
50-
51-
Crates explicitly _must not_ only be available through the following kinds of licenses:
52-
53-
- Any viral/copyleft licenses (any Affero/GPL/LGPL license),
54-
- or anything that stipulates the crate is "free for non-commercial use" (bespoke
55-
licenses),
56-
57-
If any question is not sufficiently covered by the above license reviews, please [file
58-
an
59-
issue](https://github.com/rust-seq/docs/issues/new?labels=license&title=license:%20evaluation%20of%20LICENSE).
60-
6130
## Contributable
6231

6332
Crates in the `rust-seq` stack are designed to be contributed to the community. Though
@@ -103,3 +72,34 @@ stable), `v1.y.z` is the first stable release that will always remain backwards
10372
compatible for version starting with `v1`, etc). It also means that software will not
10473
unexpectedly break once you've built on top of a particular dependency (not considering,
10574
of course, when software is in the `v0.y.z` stage).
75+
76+
## Broadly Usable
77+
78+
Crates in the `rust-seq` stack are intended to be broadly used within academic and
79+
industry. As such, they should be **freely-licensed** to enable them to be adopted used
80+
in the broadest variety of contexts. If you do not have a preference on the license, we
81+
recommend you dual license the crate to be used under the [MIT
82+
License](https://opensource.org/license/MIT) or the [Apache-2.0
83+
License](https://opensource.org/license/apache-2-0) at the user's discretion.
84+
85+
Notably, crates _must_ be made accessible under any number of the following licenses (in
86+
alphabetical order):
87+
88+
- [Apache-2.0 License](https://opensource.org/license/apache-2-0)
89+
(learn about this license [here](https://www.tldrlegal.com/license/apache-license-2-0-apache-2-0)),
90+
- [BSD 3-Clause License](https://opensource.org/license/BSD-3-clause)
91+
(learn about this license [here](https://www.tldrlegal.com/license/bsd-3-clause-license-revised)),
92+
- [MIT License](https://opensource.org/license/MIT)
93+
(learn about this license [here](https://www.tldrlegal.com/license/mit-license)),
94+
- or any public domain license (e.g.,
95+
[Unlicense](https://opensource.org/license/unlicense)).
96+
97+
Crates explicitly _must not_ only be available through the following kinds of licenses:
98+
99+
- Any viral/copyleft licenses (any Affero/GPL/LGPL license),
100+
- or anything that stipulates the crate is "free for non-commercial use" (bespoke
101+
licenses),
102+
103+
If any question is not sufficiently covered by the above license reviews, please [file
104+
an
105+
issue](https://github.com/rust-seq/docs/issues/new?labels=license&title=license:%20evaluation%20of%20LICENSE).

Diff for: ‎content/docs/writing-crates/1.checklist.md

+63-3
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,72 @@
22

33
If you're an author of a crate within the `rust-seq` stack _or_ you would like
44
to be, you can use the following checklist to ensure that your crates meet the
5-
above values. Note that these are just suggestions to adhere to the values
6-
above—completing every item is not a requirement to ratify a particular crate.
5+
above values. For each value, recommendations are listed roughly in order of
6+
most preferrable to least. Note that these are just suggestions to adhere to the
7+
values above—completing every item is not a requirement to ratify a particular
8+
crate.
79

8-
## Performance
10+
To learn more about any particular value, please see [this
11+
link](../get-started/values).
12+
13+
### Correctness
14+
15+
- [x] Write comprehensive tests to check that all invariants are upheld in the
16+
crate's logic (these also serve as documentation for your code!).
17+
- [x] If you are returning user-facing errors, consider using the
18+
[`anyhow`](https://docs.rs/anyhow/latest/anyhow) crate. Most importantly,
19+
this means (a) returning `anyhow::Result` for your `fn main()`, and (b) using the
20+
[`context()`](https://docs.rs/anyhow/latest/anyhow/trait.Context.html#tymethod.context)
21+
method to add additional context wherever errors might occur.
22+
- [x] Ensure that all errors implement
23+
[`std::error::Error`](https://doc.rust-lang.org/std/error/trait.Error.html)
24+
and that the information returned by
25+
[`std::fmt::Display`](https://doc.rust-lang.org/std/fmt/trait.Display.html)
26+
is helpful. This ensures your custom error types will work well with the
27+
broader Rust ecosystem.
28+
- [x] Use the `debug_assert!` macro throughout your code to plant sanity checks
29+
within the code. Note that this imposes no performance hits for
30+
production-compiled code (`cargo build --release`), as these statements
31+
are not included in these builds.
32+
- [x] If your crate handles user input, integrate a fuzzing suite within your
33+
tests (e.g., with [`cargo-fuzz`](https://github.com/rust-fuzz/cargo-fuzz)).
34+
35+
### Performant
936

1037
- [x] Provide benchmarks that utilize a benchmarking framework (e.g.,
1138
[Criterion](https://github.com/bheisler/criterion.rs) or
1239
[Divian](https://github.com/nvzqz/divan)) that continuous measure
1340
performance in the CI and track regressions.
41+
- [x] For each data type you expect to be heavily used by users, measure the
42+
amount of memory the type takes up and either via (a) anonymous constants or
43+
(b) unit tests, ensure that the memory required for that data type remains
44+
constant.
45+
46+
### Contributable
47+
48+
- [x] Ensure your crate is **comprehensively tested** to ensure that code can be
49+
modified and refactored by non-experts with confidence.
50+
- [x] Ensure your crate is **comprehensively linted** to ensure that code is of the
51+
highest quality possible.
52+
- [x] Ensure your crate is **comprehensively documented** to ensure that using
53+
the code is clear and straightforward. This means (a) ensuring
54+
documentation for all public-facing code, (b) ensuring documentation for
55+
all private code [to ease development in those areas], and (c) including
56+
examples for any user-facing code to make sure usage is straightforward.
57+
Note that this can be accomplished largely by enabling the
58+
[`missing_docs`](https://doc.rust-lang.org/stable/nightly-rustc/rustc_lint/builtin/static.MISSING_DOCS.html),
59+
[`clippy::missing_docs_in_private_items`](https://rust-lang.github.io/rust-clippy/master/index.html#/missing_docs_in_private_items),
60+
and
61+
[`rustdoc::missing_doc_code_examples`](https://doc.rust-lang.org/stable/nightly-rustc/rustdoc/lint/static.MISSING_DOC_CODE_EXAMPLES.html)
62+
lints.
63+
64+
### Stable
65+
66+
- [x] Ensure your crate follows [semantic versioning](https://semver.org/) and
67+
that you don't introduce breaking changes to your API without incrementing the
68+
major version number.
69+
70+
### Broadly Usable
71+
72+
- [x] Ensure that your code is available under [one of the licenses outlined in
73+
the values section](/docs/get-started/values#broadly-usable).

Diff for: ‎nuxt.config.ts

+1-1
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ export default defineNuxtConfig({
1616
content: {
1717
documentDriven: true,
1818
markdown: {
19-
remarkPlugins: [remarkGfm],
19+
remarkPlugins: { "remark-gfm": remarkGfm },
2020
rehypePlugins: [],
2121
},
2222
},

Diff for: ‎package.json

+2-2
Original file line numberDiff line numberDiff line change
@@ -11,13 +11,13 @@
1111
},
1212
"dependencies": {
1313
"@nuxt/content": "^2.13.2",
14-
"@nuxt/icon": "^1.5.4",
14+
"@nuxt/icon": "^1.5.5",
1515
"@nuxt/ui": "^2.18.6",
1616
"@nuxtjs/color-mode": "^3.5.1",
1717
"@nuxtjs/tailwindcss": "^6.12.1",
1818
"change-case": "^5.4.4",
1919
"d3": "^7.9.0",
20-
"nuxt": "^3.13.0",
20+
"nuxt": "^3.13.2",
2121
"nuxt-lucide-icons": "^1.0.5",
2222
"remark-gfm": "^4.0.0",
2323
"vue": "latest",

Diff for: ‎pages/docs/index.vue

+1-57
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<template>
2-
<div class="flex h-full w-full">
2+
<div class="flex h-full w-full dark:bg-slate-950">
33
<MoleculesDocsLeftSidebar />
44
<div class="px-16 py-10 h-full w-full">
55
<div class="prose dark:prose-invert max-w-6xl pt-4 pb-7">
@@ -106,59 +106,3 @@ import { Kind } from "~/components/molecules/docs/crate-card/kind";
106106
107107
const alertVisible = ref(true);
108108
</script>
109-
110-
<style scope lang="postcss">
111-
.card {
112-
@apply transition;
113-
114-
@apply hover:-translate-y-0.5;
115-
116-
@apply px-6;
117-
@apply py-4;
118-
119-
@apply bg-white;
120-
121-
@apply text-slate-900;
122-
123-
@apply border;
124-
@apply border-gray-100;
125-
126-
@apply rounded-lg;
127-
@apply shadow-sm;
128-
@apply hover:shadow-md;
129-
130-
@apply text-pretty;
131-
132-
.header {
133-
@apply flex justify-between items-center;
134-
135-
.title {
136-
@apply flex justify-start items-center;
137-
@apply gap-x-1;
138-
139-
@apply font-bold;
140-
font-size: 14px;
141-
@apply text-slate-600;
142-
143-
span {
144-
/* Color of the icon. */
145-
@apply bg-slate-600;
146-
}
147-
}
148-
}
149-
150-
.crate {
151-
font-family: "Space Mono";
152-
font-weight: 400;
153-
}
154-
155-
.description {
156-
@apply pt-1;
157-
158-
@apply text-gray-600;
159-
@apply text-sm;
160-
161-
@apply text-start;
162-
}
163-
}
164-
</style>

0 commit comments

Comments
 (0)