Skip to content

Commit 7b6bee9

Browse files
celaryecelarye
committed
docs: Update the contribution guidelines
1 parent 5f1a295 commit 7b6bee9

1 file changed

Lines changed: 193 additions & 49 deletions

File tree

‎.github/CONTRIBUTING.md‎

Lines changed: 193 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -1,99 +1,243 @@
1-
# Contributing Guidelines <!-- omit in toc -->
1+
<!-- omit in toc -->
2+
# Contributing Guidelines
23

34
Before checking the contributing guideline, please read through our [Code of Conduct][code-of-conduct].
45

5-
We encourage and value all types of contributions. Refer to the [Table of Contents](#table-of-contents) for guidance on how to start contributing to this project. Following the guidelines will make the experience smoother for everyone involved, and the community looks forward to your contributions!
6+
We encourage and value all types of contributions. Refer to the [Table of Contents](#table-of-contents)
7+
for guidance on how to start contributing to this project. Following the guidelines
8+
will make the experience smoother for everyone involved, and the community looks
9+
forward to your contributions!
610

7-
## Table of Contents <!-- omit in toc -->
11+
<!-- omit in toc -->
12+
## Table of Contents
13+
14+
<!-- toc -->
815

916
- [Development Contributions](#development-contributions)
10-
- [Repository Structure](#repository-structure)
11-
- [Project Conventions](#project-conventions)
12-
- [Development Workflow](#development-workflow)
13-
- [Running Scripts](#running-scripts)
14-
- [Creating a New Extension](#creating-a-new-extension)
15-
- [Open Tasks](#open-tasks)
17+
* [Repository Organization](#repository-organization)
18+
* [Repository Conventions](#repository-conventions)
19+
* [Extension Conventions](#extension-conventions)
20+
* [Development Workflow](#development-workflow)
21+
+ [Running Scripts](#running-scripts)
22+
+ [Creating a New Extension](#creating-a-new-extension)
23+
* [Open Tasks](#open-tasks)
1624
- [Documentation Contributions](#documentation-contributions)
1725
- [Support Contributions](#support-contributions)
18-
- [Answering Questions](#answering-questions)
19-
- [Validating Bug Reports](#validating-bug-reports)
20-
- [Contributing to Enhancement Suggestions](#contributing-to-enhancement-suggestions)
21-
22-
## Development Contributions
23-
24-
### Repository Structure
25-
26-
The project is organized across multiple repositories, based on the type and theme of the extensions:
27-
28-
- **Content Extensions:** Split into multiple repositories based on the theme of the target websites:
29-
30-
- Extensions for websites with **generic themes** are grouped into [theme-specific repositories][generic-theme-repositories].
31-
32-
- Extensions for websites with **non-generic or custom themes** are grouped together into [a single repository][general-extensions-repository].
33-
34-
- **Tracker Extensions:** [A dedicated repository][tracker-extensions-repository] for extensions that integrate with progress tracking services.
26+
* [Answering Questions](#answering-questions)
27+
* [Validating Bug Reports](#validating-bug-reports)
28+
* [Contributing to Enhancement Suggestions](#contributing-to-enhancement-suggestions)
3529

36-
This modular structure keeps repositories focused, maintainable, and easier to contribute to. Always ensure you're working in the appropriate repository before making changes.
30+
<!-- tocstop -->
3731

38-
### Project Conventions
39-
40-
- **Layout:** Each repository follows a shared layout defined in the [template repository][template-repository]. To propose layout changes, open an issue or pull request in that repository.
41-
42-
- **Versioning:** We use [Semantic Versioning 2.0.0][semver-2.0.0] for extension versioning.
43-
44-
- **Branch Naming:** Branches should follow the [semantic branch naming][semantic-branch-names] convention.
45-
46-
- **Commit Messages:** Use [semantic commit messages][semantic-commit-messages] to keep the commit history clear and consistent.
32+
## Development Contributions
4733

48-
- **Pull Requests:** Large pull requests that include multiple grouped changes must include a detailed description and any related issue or pull request links.
34+
> [!NOTE]
35+
> On [our website][inkdex-website] you can find more detailed documentation on [developing
36+
extensions][inkdex-website-development-docs]. These guides will help you with adhering
37+
to the guidelines found below.
38+
39+
### Repository Organization
40+
41+
The project is organized across multiple repositories, based on the type and theme
42+
of the extensions:
43+
44+
- **Content Extensions:** Split into multiple repositories based on the theme of
45+
the target websites:
46+
47+
- Extensions for websites with **generic themes** are grouped into [theme-specific
48+
repositories][generic-theme-repositories].
49+
50+
- Extensions for websites with **non-generic or custom themes** are grouped together
51+
into a [single repository][general-extensions-repository].
52+
53+
- **Tracker Extensions:** A [dedicated repository][tracker-extensions-repository]
54+
for extensions that integrate with progress tracking services.
55+
56+
This modular structure keeps repositories focused, maintainable, and easier to contribute
57+
to. Always ensure you're working in the appropriate repository before making changes.
58+
59+
### Repository Conventions
60+
61+
- **File Structure:** Each repository follows the file structure defined by the [template
62+
repository][template-repository]. To propose file structure changes, open an issue
63+
or discussion in that repository.
64+
65+
- **Branch Naming:** Branches within repositories in the [Inkdex Organization][inkdex-organization]
66+
should follow the [Conventional Branch 1.0.0][conventional-branch-spec] specification
67+
to ensure their purpose is clear and naming remains consistent.
68+
69+
- **Commit Messages:** Commit messages should follow the [Conventional Commit 1.0.0][conventional-commit-spec]
70+
specification to keep the commit history clear and consistent.
71+
72+
- **Pull Requests:** Each pull request should be focused, clearly described, and
73+
linked to related issues when applicable. Pull requests must pass all tests (see
74+
the `test` [npm script](#running-scripts)) and receive at least one approved review
75+
before merging.
76+
77+
### Extension Conventions
78+
79+
- **File Structure:** Each extension follows a standardized file structure. This
80+
helps ensure readability, maintainability, and predictability across extensions.
81+
82+
**Simple structure** (suitable for smaller extensions; not all files may be required):
83+
84+
```sh
85+
.
86+
├── forms.ts
87+
├── helpers.ts
88+
├── main.ts
89+
├── models.ts
90+
├── network.ts
91+
├── parsers.ts
92+
├── pbconfig.ts
93+
└── static
94+
└── icon.png
95+
```
96+
97+
**Advanced structure** (used for larger extensions; not all files in an implementation
98+
directory may be required; the `shared` directory is optional):
99+
100+
```sh
101+
.
102+
├── implementations
103+
│   ├── discover-section
104+
│   │  ├── helpers.ts
105+
│   │  ├── main.ts
106+
│   │  ├── models.ts
107+
│   │   └── parsers.ts
108+
│   ├── manga
109+
│   │  ├── helpers.ts
110+
│   │  ├── main.ts
111+
│   │  ├── models.ts
112+
│   │   └── parsers.ts
113+
│   ├── manga-progress
114+
│   │   ├── forms.ts
115+
│   │  ├── helpers.ts
116+
│   │  ├── main.ts
117+
│   │  ├── models.ts
118+
│   │   └── parsers.ts
119+
│   ├── search-results
120+
│   │  ├── helpers.ts
121+
│   │  ├── main.ts
122+
│   │  ├── models.ts
123+
│   │   └── parsers.ts
124+
│   ├── settings-form
125+
│   │ ├── forms.ts
126+
│   │  ├── helpers.ts
127+
│   │  ├── main.ts
128+
│   │  ├── models.ts
129+
│   │ └── parsers.ts
130+
│  └── shared
131+
│     ├── helpers.ts
132+
│     ├── main.ts
133+
│     ├── models.ts
134+
│   └── parsers.ts
135+
├── main.ts
136+
├── pbconfig.ts
137+
├── services
138+
│   └── network.ts
139+
└── static
140+
└── icon.png
141+
```
142+
143+
> [!NOTE]
144+
> The `forms.ts`, `helpers.ts`, `models.ts`, `network.ts`, and `parsers.ts` files
145+
can be turned into directories when organizing them into multiple sub-files improves
146+
clarity or maintainability.
147+
148+
- **Branding:**
149+
150+
- **Name:** The name defined in `pbconfig.ts` must exactly match the name used
151+
on the website. The directory and class names should be developer-friendly, in
152+
PascalCase, avoiding spaces and special characters.
153+
154+
- **Logo:** The logo should be taken from the website whenever possible and must
155+
be a square PNG.
156+
157+
- **Requests Rate Limiting:** Always rate-limit outgoing requests to prevent overloading
158+
websites during updates or migrations. You can use one of the following presets as
159+
a guideline if the website doesn't share their rate limit publicly (adjust as needed):
160+
161+
- **Strict:** 1 request per second
162+
163+
- **Balanced:** 3 requests per second
164+
165+
- **Loose:** 10 requests per second
166+
167+
- **Versioning:** We use the [Semantic Versioning 2.0.0][semver-2.0.0] specification
168+
for extension versions.
49169

50170
### Development Workflow
51171

52172
#### Running Scripts
53173

54-
Each repository includes useful development scripts. Refer to the `scripts` section in its `package.json` file to see what’s available (e.g., testing, bundling, formatting).
174+
Each repository includes useful development scripts. Refer to the `scripts` section
175+
in its `package.json` file to see what’s available (e.g., bundling, serving, formatting).
55176

56177
#### Creating a New Extension
57178

58179
1. Fork and clone the appropriate repository.
59-
2. Run `npm install` (requires [Node.js][node.js] and npm).
180+
2. Run `npm install` (requires [Node.js][node.js] v22+ (latest LTS) and npm).
60181
3. Add your extension code to the `src` directory.
61-
4. Run `npm test` and ensure all tests pass.
182+
4. Run `npm test` and ensure all tests pass ([husky][husky] is set up to remind you
183+
about this with a pre-push hook).
62184
5. Commit and push your changes.
63-
6. Open a pull request and contact a maintainer.
185+
6. Open a pull request.
186+
187+
A maintainer will then review your pull request and may request changes before merging.
64188

65189
### Open Tasks
66190

67-
You're welcome to work on open bug fixes or approved feature suggestions. To coordinate or ask questions, join us on our [Discord server][discord-server].
191+
You’re welcome to contribute by fixing open bug reports or implementing approved
192+
feature suggestions. To coordinate or ask questions, please open or continue an Issue
193+
or Discussion in the [extension repository][extension-repository], or reach out to
194+
us on our [Discord server][discord-server].
68195

69196
## Documentation Contributions
70197

71-
We welcome contributions that improve, update, or correct the documentation.
198+
You can find detailed documentation on [our website][inkdex-website], including guides
199+
on [installing and using extensions][inkdex-website-usage-docs] as well as [developing
200+
extensions][inkdex-website-development-docs]. We welcome and appreciate contributions
201+
that help improve, update, or correct our documentation.
72202

73203
## Support Contributions
74204

75205
### Answering Questions
76206

77-
Assist by answering questions from other community members. Questions can be asked in our [Discord server][discord-server] or in the [Q&A Discussions][q-a-discussions]. Your insights are always appreciated!
207+
Assist by answering questions from other community members. Questions can be
208+
asked in our [Discord server][discord-server] or in the [Q&A
209+
Discussions][q-a-discussions]. Your insights are always appreciated!
78210

79211
### Validating Bug Reports
80212

81-
Help ensure bugs can be addressed effectively by attempting to replicate reported issues and confirming their existence. Bug reports can be made in our [Discord server][discord-server] or in the [issue tracker][issue-tracker-bugs].
213+
Help ensure bugs can be addressed effectively by attempting to replicate
214+
reported issues and confirming their existence. Bug reports can be made in our
215+
[Discord server][discord-server] or in the [issue tracker][issue-tracker-bugs].
82216

83217
### Contributing to Enhancement Suggestions
84218

85-
Enhancement suggestions often need feedback and refinement. Contribute by reviewing and discussing these suggestions, offering your perspective, and proposing improvements. Enhancement suggestions can be made in our [Discord server][discord-server] or in the [issue tracker][issue-tracker-enhancements]. Your input helps shape the future of the project.
219+
Enhancement suggestions often need feedback and refinement. Contribute by
220+
reviewing and discussing these suggestions, offering your perspective, and
221+
proposing improvements. Enhancement suggestions can be made in our [Discord
222+
server][discord-server] or in the [issue tracker][issue-tracker-enhancements].
223+
Your input helps shape the future of the project.
86224

87225
[code-of-conduct]: https://github.com/inkdex/extensions?tab=coc-ov-file#readme
88-
[tracker-extensions-repository]: https://github.com/inkdex/tracker-extensions
226+
[inkdex-website]: https://inkdex.github.io/installation
227+
[inkdex-website-development-docs]: https://inkdex.github.io/development
89228
[generic-theme-repositories]: https://github.com/orgs/inkdex/repositories?q=topic%3Ageneric
90229
[general-extensions-repository]: https://github.com/inkdex/general-extensions
230+
[tracker-extensions-repository]: https://github.com/inkdex/tracker-extensions
91231
[template-repository]: https://github.com/inkdex/template-extensions
232+
[inkdex-organization]: https://github.com/inkdex
233+
[conventional-branch-spec]: https://conventional-branch.github.io
234+
[conventional-commit-spec]: https://www.conventionalcommits.org/en/v1.0.0
92235
[semver-2.0.0]: https://semver.org/spec/v2.0.0.html
93-
[semantic-branch-names]: https://gist.github.com/seunggabi/87f8c722d35cd07deb3f649d45a31082
94-
[semantic-commit-messages]: https://gist.github.com/joshbuchea/6f47e86d2510bce28f8e7f42ae84c716
95236
[node.js]: https://nodejs.org
237+
[husky]: https://typicode.github.io/husky
238+
[extension-repository]: https://github.com/inkdex/extensions
96239
[discord-server]: https://discord.gg/inkdex
240+
[inkdex-website-usage-docs]: https://inkdex.github.io/installation
97241
[q-a-discussions]: https://github.com/inkdex/extensions/discussions/categories/q-a
98242
[issue-tracker-bugs]: https://github.com/inkdex/extensions/issues?q=is%3Aissue+is%3Aopen+label%3Abug
99243
[issue-tracker-enhancements]: https://github.com/inkdex/extensions/issues?q=label%3Aenhancement

0 commit comments

Comments
 (0)