From 61e41f247bdf065f506846421d38de5e4415afa7 Mon Sep 17 00:00:00 2001 From: Xin Date: Sun, 10 Sep 2023 12:07:04 +0100 Subject: [PATCH] chore: add contributing guide [skip ci] --- .github/CONTRIBUTING.md | 110 ++++++++++++++++++++++++++++++++++++++++ .vscode/settings.json | 3 +- README.md | 5 +- 3 files changed, 116 insertions(+), 2 deletions(-) create mode 100644 .github/CONTRIBUTING.md diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 00000000..3dcf70b1 --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,110 @@ +# Contribute to Hextra + +👋 Thank you for being interested in contributing to Hextra! As an open source project, we welcome contributions of many forms including bug reports, feature requests, documentation improvements, and code contributions. + + +## Table of Contents + +- [Guidelines](#guidelines) + - [Contributing Code](#contributing-code) + - [Contributing Documentation](#contributing-documentation) + - [💬 GitHub Discussions](#-github-discussions) + - [GitHub Issues](#github-issues) +- [Development](#development) + - [Local development setup](#local-development-setup) + - [Project structure](#project-structure) + - [Start the development server](#start-the-development-server) + - [Compile the styles](#compile-the-styles) + + +## Guidelines + +### Contributing Code + +To contribute, please follow the ["Fork and Pull Request"][fork and pull] workflow： + +Fork the repository, make your changes, and then submit a pull request. +Please make sure to include a description of the changes you made and why you made them. +Use [Conventional Commits][conventional commits] message to make it easier to understand the changes you made. + +### Contributing Documentation + +Similar to contributing code, you can also contribute to the documentation by submitting a pull request. + +The documentation site is located in the [`exampleSite`](../exampleSite/) folder. +You can make changes to the documentation and create a pull request. A preview of the new documentation will be automatically generated and displayed in the pull request comment via [Netlify][netlify deploy preview]. + +### 💬 GitHub Discussions + +We’re using [Discussions][discussions] as a place to connect with other members using Hextra: + +- Ask questions you’re wondering about. +- Share ideas. +- Engage with other users. + +### GitHub Issues + +If you find a bug or have a feature request, please [open an issue][issues]. + +Please make sure to include a description of the bug or feature you are requesting. If you are reporting a bug, please include steps to reproduce the bug. + +We recommend that you search existing [issues][issues] or discussions before opening a new one to prevent duplicates. + +## Development + +> **Note** +> You can start developing on [GitHub Codespaces][open in codespaces] or use [devcontainer][devcontainer] locally without installing any dependencies. + +### Local development setup + +- [Hugo][hugo] >= v0.115.0 (extended version) +- [Node.js][nodejs] +- [Go][go] + +Install dependencies: + +```bash +npm i +``` + +### Project structure + +- [`assets`](../assets/): CSS styles and JavaScript files. +- [`data`](../data/): The theme data files. Now only contains the `icons.yaml` file. +- [`exampleSite`](../exampleSite/): The documentation site for the theme. +- [`i18n`](../i18n/): The theme translation files. +- [`layouts`](../layouts/): The theme layouts. +- [`static`](../static/): The static files for the theme. For example, the favicon and the site logo. + +Please refer to the [Hugo documentation][hugo] for more information. + +### Start the development server + +```bash +npm run dev:theme +``` + +It will start the Hugo server on `http://localhost:1313/` for the `exampleSite` content. + +### Compile the styles + +For development preview, we compile the Tailwind CSS styles on the fly. But for production, we need to compile the styles first. + +```bash +npm run build:css +``` + +It will compile the Tailwind CSS styles and generate the `assets/css/compiled/main.css` file. + + + +[fork and pull]: https://docs.github.com/en/get-started/quickstart/contributing-to-projects +[conventional commits]: https://www.conventionalcommits.org +[issues]: https://github.com/imfing/hextra/issues +[discussions]: https://github.com/imfing/hextra/discussions +[nodejs]: https://nodejs.org/en/ +[hugo]: https://gohugo.io/ +[go]: https://golang.org/doc/install +[devcontainer]: https://code.visualstudio.com/docs/devcontainers/containers +[open in codespaces]: https://codespaces.new/imfing/hextra +[netlify deploy preview]: https://docs.netlify.com/site-deploys/deploy-previews/ diff --git a/.vscode/settings.json b/.vscode/settings.json index 9460f5e2..d2386390 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -1,4 +1,5 @@ { "editor.tabSize": 2, - "css.customData": [".vscode/tailwind.json"] + "css.customData": [".vscode/tailwind.json"], + "markdown.extension.toc.levels": "2..6" } diff --git a/README.md b/README.md index 6ee174ed..b19ae644 100644 --- a/README.md +++ b/README.md @@ -31,13 +31,16 @@ Using the [Hextra Starter Template](https://github.com/imfing/hextra-starter-tem The template repository also includes a [GitHub Actions workflow](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-with-a-custom-github-actions-workflow) for deploying your website to GitHub Pages. +Hextra Starter Template + ### Usage Refer to the [documentation](https://imfing.github.io/hextra/docs) for more information. ## Contributing -This project is actively under development. Contributions are welcome! +Contributions are welcome! +Check out the [contributing guide](.github/CONTRIBUTING.md) to get started. ## License