Skip to content

Contributing

Jump to bottom
Laeth English edited this page Aug 30, 2023 · 2 revisions

Welcome to WikiDB, and thank you for showing interest in contributing! If you want to improve this software or this documentation, please don't hesitate to contribute. This document provides general advice and guidelines for contributing to this project. Your help and interest is greatly appreciated.

Getting Started

To develop, you will need git for source control and .NET SDK version 7 on your machine. To get your local development copy:

  1. Fork this repo. You can fork this repository onto your account with the fork button on the repo's home page.
  2. Clone the forked repo onto your development machine:
git clone https://github.com/<username>/wikidb.git
cd wikidb
  1. Add this repository as your remote:
git remote add upstream https://github.com/PilotGuy772/wikidb
  1. Prepare dotnet:
dotnet restore
dotnet build --no-restore
dotnet test

Note that you are STRONGLY encouraged to use SSH authorization and signing for your contributions. You wont have to login with username/password and it is more secure. You can find information here. When using SSH with git, make sure to use the SSH-formatted URIs instead of HTTP-formatted ones (for example, git@github.com:/<username>/<project>).

Contribution Workflow

Once you have your personal fork on your local machine, you should do the following to make sure you are ready to start working:

  1. Checkout the dev branch:
git checkout dev
  1. Pull from upstream (this repo) to sync with the latest changes:
git pull upstream dev
  1. Create a new feature/fix branch for your contribution. Contributions should be separated by the feature or bug that is being addressed. If possible, reference a specific issue in your branch name or pull request, especially if you are fixing a bug.
# for a new feature
git checkout -b feature/feature-name
# for a bug fix
git checkout -b fix/issue-123

Now you are ready to get to work. You are free to commit as much as you like and push as much as you like to your personal fork (if you followed these instructions, this will be the repo located at the remote origin). Make sure to thoroughly test your work to try and find bugs with the software. We will publish full testing guidelines soon to give guidance on what to test before you move on.

Commit, Push, and Pull Request

Once you are happy with your changes, you will have to commit your changes and push to your fork:

git add *
git commit -m "<commit-message>"
git push origin <your-feature-branch>

replace with a description of your changes and with the name of the feature/fix branch you are using

Now, you will have to return to Github to open a pull request with the main repository. Navigate to your new feature branch and open a new pull request with dev. Review your changes and write a descriptive title and description. If your change addresses specific issues, include keywords like "Fixes #123" or "Resolved #456" to link the pull request with the issue. Github should also give you an overview of your changes. Review and make sure everything looks good.

Once you open your pull request, maintainers and other contributors will see your pull request on the main repository. Please take all feedback and criticism and make necessary changes to your work. Once your pull request is approved, your changes will be merged with the appropriate dev branch.

Semantic Versioning and Releases

WikiDB uses semantic versioning for releases. The master branch always reflects the current release, while dev is used to stage upcoming releases. Whenever dev is merged with master, a Github Workflow automates the building, testing, and packaging process and prepares a new draft release. Releases are incremented often according to the rules of semver. Sometimes, maintainers will decide that it is time to prepare for a new major release. At this point, we will focus on the primary feature(s) and changes that are central to the new major release, and we will focus mainly on bug fixes and patches.

If you think it is time to merge dev with master for a new release, open a new issue and give it the appropriate tag. Explain how you think the release should be incremented and why you think so.

Contributing to Documentation

You can also contribute to the docs. Contributing to documentation and this wiki is a great way to get your feet wet. You can simple visit any page and edit it, or create a new page. Contribute how you see fit, and leave a descriptive message explaining your contribution. You may even update this page if you have improvements in mind.

Clone this wiki locally