From 3de03d9d56e0df1c5b02234060edfd61b00d1c6c Mon Sep 17 00:00:00 2001 From: Alex Gleason Date: Mon, 18 Jul 2022 11:46:59 -0500 Subject: [PATCH] Rewrite contributing docs --- docs/contributing.md | 85 +++++++++++++++++--------------------------- 1 file changed, 32 insertions(+), 53 deletions(-) diff --git a/docs/contributing.md b/docs/contributing.md index ba2fa09ac..47a7b747d 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -1,55 +1,34 @@ # Contributing to Soapbox -When contributing to Soapbox, please first discuss the change you wish to make via issue, -email, or any other method with the owners of this repository before making a change. - -## Project Contribution Flow - -It is recommended that you use the following guidelines to contribute to the Soapbox project: - -* Understand recommended [GitLab Flow](https://www.youtube.com/watch?v=InKNIvky2KE) methods on branch management -* Use the following branch management process: - * Pull a fork - * Mirror the fork against the original repository, setting the mirror to only mirror to protected branches - * Set the master branch in your fork to Protected - * Never modify the master branch in your fork, so that your fork mirroring does not break - * Pull branches in your fork to solve specific issues - * Do merge requests only to the original repository master branch, so that your fork mirroring does not break -* If you don't use the above policy, when your mirrored fork breaks mirroring, you can force your fork to back to successful mirroring using the following process: - * Unprotect the master branch of your fork from force push - * Use the following git commands from the cmd line of your local copy of your fork's master branch - ``` - git remote add upstream /url/to/original/repo - git fetch upstream - git checkout master - git reset --hard upstream/master - git push origin master --force - ``` - * Re-protect the master branch of your fork from force push - -## Pull Request Process - -1. Ensure any install or build dependencies are removed before the end of the layer when doing a - build. -2. Update the README.md with details of changes to the interface, this includes new environment - variables, exposed ports, useful file locations and container parameters. -3. Increase the version numbers in any examples files and the README.md to the new version that this - Pull Request would represent. The versioning scheme we use is [SemVer](http://semver.org/). -4. You may merge the Pull Request in once you have the sign-off of two other developers, or if you - do not have permission to do that, you may request the second reviewer to merge it for you. - -## Text Editor Tools - -If you're using a text editor like [Atom](https://atom.io/) or [Visual Studio Code](https://code.visualstudio.com/), you can install tools to help you get linter feedback while you write code for the Soapbox project. - -For Atom, you can install the following packages: - -* [linter](https://atom.io/packages/linter) -* [linter-ui-default](https://atom.io/packages/linter-ui-default) -* [linter-eslint](https://atom.io/packages/linter-eslint) -* [linter-stylelint](https://atom.io/packages/linter-stylelint) - -For Visual Studio Code, you can install the following extensions: - -* [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) -* [vscode-stylelint](https://marketplace.visualstudio.com/items?itemName=stylelint.vscode-stylelint) +Thank you for your interest in Soapbox! + +When contributing to Soapbox, please first discuss the change you wish to make by [opening an issue](https://gitlab.com/soapbox-pub/soapbox-fe/-/issues). + +## Opening an MR (merge request) + +1. Smash that "fork" button on GitLab to make a copy of the repo. +2. Clone the repo locally, then begin work on a new branch (eg not `develop`). +3. Push your branch to your fork. +4. Once pushed, GitLab should provide you with a URL to open a new merge request right in your terminal. If not, do it [manually](https://gitlab.com/soapbox-pub/soapbox-fe/-/merge_requests/new). + +### Ensuring the CI pipeline succeeds + +When you push to a branch, the CI pipeline will run. + +[Soapbox uses GitLab CI](https://gitlab.com/soapbox-pub/soapbox-fe/-/blob/develop/.gitlab-ci.yml) to lint, run tests, and verify changes. +It's important this pipeline passes, otherwise we cannot merge the change. + +New users of gitlab.com may see a "detatched pipeline" error. +If so, please check the following: + +1. Your GitLab email address is confirmed. +2. You may have to have a credit card on file before the CI job will run. + +## Text editor + +We recommend developing Soapbox with [VSCodium](https://vscodium.com/) (or its proprietary ancestor, [VS Code](https://code.visualstudio.com/)). + +This will help give you feedback about your changes _in the editor itself_ before GitLab CI performs linting, etc. + +When this project is opened in Code it will automatically recommend extensions. +See [`.vscode/extensions.json`](https://gitlab.com/soapbox-pub/soapbox-fe/-/blob/develop/.vscode/extensions.json) for the full list.