From 934219b659608395ede123ab2a4f0dd3980f49cb Mon Sep 17 00:00:00 2001 From: Oliver Date: Sat, 15 Mar 2025 00:06:43 +0100 Subject: [PATCH] docs: Add contributing and guidelines documentation --- docs/src/fancynpcs/fancynpcs.md | 2 +- docs/src/guidelines/contributing.md | 48 ++++++++++++++++++++ docs/src/guidelines/guidelines.md | 5 +++ docs/src/guidelines/monorepo.md | 53 ++++++++++++++++++++++ docs/src/guidelines/versioning.md | 69 +++++++++++++++++++++++++++++ 5 files changed, 176 insertions(+), 1 deletion(-) create mode 100644 docs/src/guidelines/contributing.md create mode 100644 docs/src/guidelines/guidelines.md create mode 100644 docs/src/guidelines/monorepo.md create mode 100644 docs/src/guidelines/versioning.md diff --git a/docs/src/fancynpcs/fancynpcs.md b/docs/src/fancynpcs/fancynpcs.md index 245dd612..08dbc2f4 100644 --- a/docs/src/fancynpcs/fancynpcs.md +++ b/docs/src/fancynpcs/fancynpcs.md @@ -2,7 +2,7 @@ title: FancyNpcs icon: accessibility expanded: true -order: 2 +order: 10 --- # diff --git a/docs/src/guidelines/contributing.md b/docs/src/guidelines/contributing.md new file mode 100644 index 00000000..38c7530f --- /dev/null +++ b/docs/src/guidelines/contributing.md @@ -0,0 +1,48 @@ +--- +order: 10 +--- +# Contributing + +This topic is all about the development guidelines that we follow. It is important to follow these +guidelines to maintain the quality of the code and to make sure that the code is consistent and easy to read. + +## Pull Requests + +Generally pull requests are welcome. However, it is important to follow the guidelines below when creating a pull +request. + +If you plan to make a major change to the code, please join our discord server and discuss it with us before creating a +pull request out of nowhere. + +### Code Style + +Please try to adapt to the code style that is already present in the project. If you are unsure about the code style, +please join our discord server and ask for help. + +If you have suggestions for a better code style, please join our discord server and discuss it with us. + +### Commit Messages + +Please make sure that your commit messages are clear and concise. It is important to write a good commit message so that +it is easy to understand what the commit is about. + +Keep the commit message short and to the point. If you need to write a longer message, please use the body of the +commit. + +Follow the format described in the [Monorepo](monorepo.md) guidelines. + +### Testing + +Please make sure that your code is tested before marking the pull request as ready for review. This means that the code +should compile and run without any errors. If you are unsure about how to test your code, please join our discord server +and ask for help. + +When creating a PR for FancyNpcs please run the `/fancynpcs test` command in-game and attach a screenshot of the output +to the PR. + +### Documentation + +Please add documentation to your code. This means that you should add comments to your code so that it is easy +to understand what the code is doing. Also, please add Javadocs to the code if it is a public API. + +If you modified, added or removed any commands, please update the `/npcs help` messages and the docs. \ No newline at end of file diff --git a/docs/src/guidelines/guidelines.md b/docs/src/guidelines/guidelines.md new file mode 100644 index 00000000..f154c81b --- /dev/null +++ b/docs/src/guidelines/guidelines.md @@ -0,0 +1,5 @@ +--- +order: 1 +icon: shield +redirect: contributing +--- \ No newline at end of file diff --git a/docs/src/guidelines/monorepo.md b/docs/src/guidelines/monorepo.md new file mode 100644 index 00000000..2b34c1d9 --- /dev/null +++ b/docs/src/guidelines/monorepo.md @@ -0,0 +1,53 @@ +--- +order: 8 +--- +# Monorepo + +## What is a monorepo? + +A monorepo (monolithic repository) is a version control strategy where multiple related projects, such as Minecraft plugins and libraries, reside within a single repository. +Instead of maintaining separate repositories for each plugin or library, all codebases share the same version control system, dependencies, and development workflow. + +## Benefits of a Monorepo + +- **Code Reuse**: Share common libraries between plugins without duplication. +- **Simplified Dependency Management**: Easily reference shared libraries without external repositories. +- **Consistent Development Workflow**: Standardized build tools and CI/CD pipelines across all projects. +- **Atomic Changes**: Simultaneously update multiple plugins and libraries within the same commit. +- **Easier Refactoring**: Modify shared code with full visibility of its impact on all projects. + +## Repository Structure + +The dependencies between plugins and libraries are managed using Gradle, a build automation tool for Java projects. + +There are three main folders in the monorepo: + +- `plugins/`: Contains all Minecraft plugins. +- `libraries/`: Contains all shared libraries. +- `docs/`: Contains documentation for the plugins and libraries. + +## Development Workflow + +1. Clone the Repository +2. Make Changes +3. Test Changes +4. Commit Changes +5. Push Changes +6. Review Changes +7. Merge Changes +8. Publish Changes +9. Monitor Changes + +Commit messages should follow this format: + +``` +: +``` + +scope: The affected component (e.g., plugin, library, docs, ci etc.) + +Example: + +``` +fancynpcs: Fix NPE in teleport command +``` \ No newline at end of file diff --git a/docs/src/guidelines/versioning.md b/docs/src/guidelines/versioning.md new file mode 100644 index 00000000..baef6db6 --- /dev/null +++ b/docs/src/guidelines/versioning.md @@ -0,0 +1,69 @@ +--- +order: 9 +--- +# Versioning + +The version is structured as follows: `major.minor.patch.`. The build id is optional and is only used for +development builds. + +## Semver + +### Major + +The major version is increased when there are very significant changes to the codebase. This could be a complete rewrite +of the codebase or a major change in the way the plugin works. This is usually not done very often. When the major +version is increased, the minor and patch versions are reset to 0. + +Data might be lost when updating to a new major version. + +Breaking changes in the API are expected when updating to a new major version. + +### Minor + +The minor version is increased when there are new features added to the codebase. This could be new commands, new +features or support for a new minecraft version. This is done more often than increasing the major version. When the +minor version is increased, the patch version is reset to 0. + +Data will not be lost when updating to a new minor version. + +Breaking changes in the API are expected when updating to a new minor version. + +### Patch + +The patch version is increased when there are bug fixes or small changes to the codebase. This is done very often. + +Data will not be lost when updating to a new patch version. + +Breaking changes in the API are not expected when updating to a new patch version. + +### Build + +The build id is optional and is only used for development builds. The build id is increased every time a new build is +created. + +- Development builds are not recommended for production use. +- Development builds might contain bugs. +- Development builds might contain incomplete features. +- Development builds might contain breaking changes. +- Development builds might contain experimental features. +- Development builds might contain untested features. +- Development builds might contain unoptimized code. +- Development builds might contain security vulnerabilities. +- Development builds might contain incomplete documentation. +- Development builds might cause data loss. +- Development builds might cause server crashes. +- Development builds might cause server lag. +- Development builds might cause other issues. + +## Changelog + +Every release should have a changelog. The changelog will be added to all platforms where the plugin is available. The +changelog should contain the following information: + +- The version number +- A list of changes that were made in this release +- A list of bug fixes that were made in this release +- A list of new features that were added in this release + +There are mostly changes list that are important to server admins. Breaking changes to the API might not be listed in +the changelog. \ No newline at end of file