mirror of
https://github.com/hugo-fixit/FixIt.git
synced 2026-08-24 15:28:57 +00:00
Cell
171 lines
7.4 KiB
Markdown
171 lines
7.4 KiB
Markdown
# CONTRIBUTING
|
|
|
|
Make sure that you follow [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) while contributing and engaging in the discussions.
|
|
|
|
## Prerequisites
|
|
|
|
Before you start contributing, make sure you have the following tools installed:
|
|
|
|
- **Node.js** (>= 20.0.0) - Required for package management and build tools
|
|
- **Hugo Extended** (>= 0.147.7) - The static site generator
|
|
- **pnpm** - Package manager (recommended)
|
|
|
|
You can check your installed versions:
|
|
|
|
```bash
|
|
node --version
|
|
hugo version
|
|
pnpm --version
|
|
```
|
|
|
|
## How to contribute to this project
|
|
|
|
First, fork this repository by clicking the fork button.
|
|
|
|
Next, clone your forked repo.
|
|
|
|
```bash
|
|
git clone https://github.com/hugo-fixit/FixIt.git && cd FixIt
|
|
```
|
|
|
|
Then, install the dev dependencies.
|
|
|
|
```bash
|
|
pnpm install
|
|
```
|
|
|
|
And now you are ready to go!
|
|
|
|
Here are some useful commands for development:
|
|
|
|
### Development
|
|
|
|
```bash
|
|
# Run local server with demo content
|
|
pnpm dev
|
|
|
|
# Run local server with test content
|
|
pnpm test
|
|
|
|
# Run local server with documentation (requires fixit-docs as sibling directory)
|
|
pnpm dev:docs
|
|
```
|
|
|
|
> [!TIP]
|
|
>
|
|
> - You can run `pnpm dev -e production` or `pnpm test -e production` to check the production environment.
|
|
> - If you want to work on documentation-related theme changes, the simplest way is to have both `FixIt` and `fixit-docs` cloned as sibling directories.
|
|
|
|
### Building
|
|
|
|
```bash
|
|
# Build demo site
|
|
pnpm build
|
|
|
|
# Build test site
|
|
pnpm build:test
|
|
|
|
# Build both demo and test sites for deployment (includes public directory reorganization)
|
|
pnpm build:vercel
|
|
```
|
|
|
|
### Preview
|
|
|
|
```bash
|
|
# Preview the built site locally (requires build:vercel first)
|
|
pnpm preview
|
|
```
|
|
|
|
## Project Structure
|
|
|
|
Understanding the project structure will help you contribute more effectively:
|
|
|
|
```
|
|
FixIt/
|
|
├── archetypes/ # Content templates
|
|
├── assets/ # Theme assets (CSS, JS, images)
|
|
│ ├── css/ # SCSS stylesheets
|
|
│ ├── js/ # JavaScript files
|
|
│ └── lib/ # Third-party libraries
|
|
├── demo/ # Demo site for development
|
|
├── i18n/ # Internationalization files
|
|
├── layouts/ # Hugo template files
|
|
│ ├── _markup/ # Hugo render hooks
|
|
│ ├── _partials/ # Reusable template components
|
|
│ └── _shortcodes/ # Custom shortcodes
|
|
├── static/ # Static files
|
|
├── test/ # Test site content
|
|
├── package.json # npm scripts and dependencies
|
|
└── hugo.toml # Default theme configuration
|
|
```
|
|
|
|
## Development Workflow
|
|
|
|
1. **Make your changes** in the appropriate directories
|
|
2. **Test locally** using `pnpm dev` or `pnpm test`
|
|
3. **Check different environments** with production builds
|
|
4. **Verify documentation** changes with `pnpm dev:docs` (if applicable)
|
|
5. **Commit your changes** following the commit message format below
|
|
|
|
## Pull Request Guidelines
|
|
|
|
- Create a feature branch from `main`
|
|
- Make your changes with clear, focused commits
|
|
- Test your changes thoroughly
|
|
- Update documentation if needed
|
|
- Submit a pull request with a clear description
|
|
|
|
Finally, create a new pull request at <https://github.com/hugo-fixit/FixIt/pulls> to submit your contribution 🎉
|
|
|
|
## Git standard for developers
|
|
|
|
### Branches
|
|
|
|
| Branch | Description |
|
|
| :------------- | :----------------------------------------------------- |
|
|
| main | _The development branch, may contain unstable updates_ |
|
|
| single feature | _The branch to enhancements or fixes_ |
|
|
|
|
### Merge events
|
|
|
|
| event | merge |
|
|
| :------------- | :------------------------------------ |
|
|
| PR | **others:main => main:** `--rebase` |
|
|
| single feature | **feature branch => main:** `--merge` |
|
|
|
|
### Commit message
|
|
|
|
#### Format
|
|
|
|
`[{emoji} ]{type}[({scope})]: {subject within 50 words}[ (#{issue/pull request})]`
|
|
|
|
example:
|
|
|
|
- :tada: Feat: add shortcode fixit-encryptor shortcode (#123)
|
|
- :arrow_up: Chore(libs): update Artalk from 2.2.12 to 2.3.4 (#150)
|
|
|
|
#### Emoji
|
|
|
|
- <https://gitmoji.dev>
|
|
- [vscode plugin](https://github.com/maixiaojie/git-emoji-zh.git)
|
|
- utools plugin `GitEmoji`
|
|
|
|
#### Message
|
|
|
|
| Emoji | Type | Example | Description (No Ambiguous) |
|
|
| :-------------------------------------------- | :------- | :----------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| :tada:<br>:sparkles: | Feat | Feat: add {feature} | new feature |
|
|
| :truck: | | Feat: adjust/migrate {feature name}, {change details} | For the adjustment feature, it is necessary to describe the current situation (before) and after adjustment (after) |
|
|
| :fire: | | Feat: delete {feature name}, {deletion reason} | If the feature is deleted, the reason for deletion must be explained |
|
|
| :bug: <br>:construction: <br>:rotating_light: | Fix | Fix: fix {bug description} | Fix known bugs |
|
|
| :art: <br>:lipstick: <br>:pencil2: | Style | Style: Typesetting/CSS style {optimizing content} | Changes that do not affect code operation, such as code layout and style change |
|
|
| :recycle: | Refactor | Refactor: override {feature name} | It is neither a new function nor a code change to fix a bug. Simply rewriting the code of a function does not affect the function result |
|
|
| :zap: | Perf | Perf: improve performance {function name}, {improve content} | Optimize code performance |
|
|
| :rewind: | Revert | Revert: restore version {commit message of restore version} | Restore the version of one commit |
|
|
| :pencil:<br>:pencil2: | Docs | Docs: revise comments/update documents | Adjustment of documents and notes |
|
|
| :wrench: | Chore | Chore: update plugin version | Changes in the construction process or auxiliary tools |
|
|
|
|
> [!NOTE]
|
|
> The change log is automatically generated based on the commit message.\
|
|
> A add `(ignore)` or `(i)` scope to ignore including in.
|