Skip to content

Commit f738289

Browse files
jeansordesjeansordes
committed
docs: improve documentation
1 parent 93f1538 commit f738289

File tree

2 files changed

+210
-197
lines changed

2 files changed

+210
-197
lines changed

‎CONTRIBUTING.md

+181
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,181 @@
1+
# Contributing
2+
3+
## Development
4+
5+
### Prerequisites
6+
7+
- [Node.js](https://nodejs.org/) (v16 or higher)
8+
- [npm](https://www.npmjs.com/) (comes with Node.js)
9+
10+
### Setup
11+
12+
1. Clone this repository to your local machine
13+
2. Navigate to the project directory
14+
3. Install dependencies:
15+
```bash
16+
npm install
17+
```
18+
4. For development with hot-reload:
19+
```bash
20+
npm run dev
21+
```
22+
5. For production build:
23+
```bash
24+
npm run build
25+
```
26+
27+
### Commit Guidelines
28+
29+
This project uses [Commitizen](https://github.com/commitizen/cz-cli) to standardize commit messages, which helps with automatic changelog generation. Instead of using `git commit`, please use:
30+
31+
```bash
32+
npm run commit
33+
```
34+
35+
This will prompt you to fill in standardized commit message fields:
36+
- **Type**: The type of change (feat, fix, docs, style, refactor, perf, test, chore)
37+
- **Scope**: The part of the codebase affected (optional)
38+
- **Subject**: A short description of the change
39+
- **Body**: A longer description (optional)
40+
- **Breaking Changes**: Any breaking changes (optional)
41+
- **Issues**: Issue references (optional)
42+
43+
Following this convention makes the changelog more useful and helps with semantic versioning.
44+
45+
### Testing in Obsidian
46+
47+
1. Create a symbolic link or copy the built files to your Obsidian vault's plugins folder:
48+
```bash
49+
# Example (adjust paths as needed)
50+
ln -s /path/to/project /path/to/vault/.obsidian/plugins/another-dendron-plugin
51+
```
52+
2. Restart Obsidian or reload plugins
53+
3. Enable the plugin in Obsidian settings
54+
55+
## Releasing New Versions
56+
57+
This plugin includes automated release scripts to simplify the versioning and publishing process. The release process includes automatic changelog generation based on your commit history and uses GitHub Actions to create releases.
58+
59+
### Release Process
60+
61+
1. Make your changes to the codebase
62+
2. Run one of the following commands:
63+
```bash
64+
# For a patch version bump (e.g., 1.0.0 -> 1.0.1)
65+
npm run release
66+
67+
# For a minor version bump (e.g., 1.0.0 -> 1.1.0)
68+
npm run release:minor
69+
70+
# For a major version bump (e.g., 1.0.0 -> 2.0.0)
71+
npm run release:major
72+
```
73+
74+
This will:
75+
- Build the plugin
76+
- Bump the version number
77+
- Generate/update the changelog
78+
- Create a git commit
79+
- Create a tag with the exact version number
80+
- Push the commit and tag to GitHub
81+
- **Trigger the GitHub Actions workflow that will:**
82+
- Build the plugin again
83+
- Create a GitHub release
84+
- Attach the necessary files (main.js, manifest.json, styles.css)
85+
86+
> **Note**: This method requires no additional setup beyond having push access to the repository.
87+
88+
### Manual Release Process
89+
90+
If you prefer more control over the process, you can manually trigger the GitHub Actions workflow:
91+
92+
1. Manually bump the version and create a tag:
93+
```bash
94+
# First, update the version in package.json, manifest.json, and versions.json
95+
npm run version-bump
96+
97+
# Commit the changes
98+
git add .
99+
git commit -m "Bump version to x.y.z"
100+
101+
# Create a tag with the exact version number (no 'v' prefix)
102+
git tag -a "x.y.z" -m "Release x.y.z"
103+
104+
# Push both the commit and the tag to GitHub
105+
git push origin master --tags
106+
```
107+
108+
> **Important**: According to Obsidian's guidelines, tag names should be just the version number (e.g., `1.0.0`) without the `v` prefix. The GitHub Actions workflow is configured to trigger only on tags that match this pattern.
109+
110+
2. The GitHub Actions workflow will automatically:
111+
- Build the plugin
112+
- Create a GitHub release with the tag name
113+
- Attach the necessary files (main.js, manifest.json, styles.css)
114+
115+
### Changelog Generation
116+
117+
The release process automatically generates a CHANGELOG.md file based on your commit history. To make the most of this feature:
118+
119+
1. Always use the structured commit format with `npm run commit`
120+
2. Follow the [Conventional Commits](https://www.conventionalcommits.org/) specification
121+
3. Use appropriate commit types:
122+
- `feat`: A new feature (triggers a minor version bump)
123+
- `fix`: A bug fix (triggers a patch version bump)
124+
- `docs`: Documentation changes
125+
- `style`: Code style changes (formatting, etc.)
126+
- `refactor`: Code changes that neither fix bugs nor add features
127+
- `perf`: Performance improvements
128+
- `test`: Adding or updating tests
129+
- `chore`: Changes to the build process or auxiliary tools
130+
131+
To manually generate or update the changelog without releasing:
132+
```bash
133+
npm run changelog
134+
```
135+
136+
To regenerate the entire changelog from scratch:
137+
```bash
138+
npm run changelog:first
139+
```
140+
141+
## Contributing
142+
143+
Contributions are welcome! Please feel free to submit a Pull Request.
144+
145+
1. Fork the repository
146+
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
147+
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
148+
4. Push to the branch (`git push origin feature/amazing-feature`)
149+
5. Open a Pull Request
150+
151+
## License
152+
153+
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
154+
155+
## Troubleshooting
156+
157+
### Release Process Issues
158+
159+
- **Error: src refspec main does not match any**: This means the branch name in the release script doesn't match your actual branch name. The script is configured to use the `master` branch.
160+
161+
- **Error: main.js does not exist**: Make sure to run the build script before releasing. The release script should handle this automatically, but you can run `npm run build` manually if needed.
162+
163+
- **GitHub Actions not triggering**: Ensure you've pushed both the commit and the tag to the remote repository. For the automated process, check if the tag was successfully pushed with `git push origin <tag-name>`.
164+
165+
- **Error: GitHub Releases requires a tag**: This error occurs in GitHub Actions when trying to create a release without a proper tag. Make sure:
166+
1. You've created a tag with the exact version number (e.g., `1.0.0`, not `v1.0.0`)
167+
2. You've pushed the tag to GitHub with `git push origin <tag-name>` or `git push origin --tags`
168+
3. The tag format matches the pattern in the workflow file (`[0-9]+.[0-9]+.[0-9]+`)
169+
170+
- **Error: Resource not accessible by integration**: This error occurs when the GitHub Actions workflow doesn't have the necessary permissions to create releases. Make sure your workflow file includes the following permissions:
171+
```yaml
172+
permissions:
173+
contents: write
174+
```
175+
176+
- **Tag naming convention**: Obsidian requires tags to be just the version number (e.g., `1.0.0`) without the `v` prefix. All scripts have been updated to follow this convention.
177+
178+
- **GitHub Actions workflow failed**: If the GitHub Actions workflow fails:
179+
1. Check the workflow logs in the GitHub Actions tab of your repository
180+
2. Ensure the tag was properly created and pushed
181+
3. Verify that the GitHub Actions workflow has the necessary permissions to create releases

0 commit comments

Comments
 (0)