twin/xmonad
1
0
Fork 0
mirror of https://github.com/xmonad/xmonad.git synced 2025-05-19 08:30:21 -07:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #342 from TheMC47/contributing-changes

Browse Source 
CONTRIBUTING: Update to reflect current practices
This commit is contained in:
Tomáš Janoušek 2022-06-13 11:39:34 +02:00 committed by GitHub
commit 0c8ed88d8a
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 19 additions and 81 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

100
CONTRIBUTING.md
View File

@ -70,8 +70,11 @@ Here are some tips for getting your changes merged into xmonad:
and [xmonad][] have test-suites that you could run with
`stack test` for example.
* Make sure you read the section on rebasing and squashing commits
below.
* When committing, try to follow existing practices. For more
information on what good commit messages look like, see [How to
Write a Git Commit Message][commit-cbeams] and the [Kernel
documentation][commit-kernel] about committing logical changes
separately.
## Style Guidelines
@ -83,7 +86,7 @@ as well!
and provide a type signature; use Haddock syntax in the comments.
* Follow the coding style of the module that you are making changes to
(`n` spaces for indentation, where to break long type signatures, …)
(`n` spaces for indentation, where to break long type signatures, …).
* New code should not introduce any new warnings. If you want to
check this yourself before submitting a pull request, there is the
@ -95,7 +98,7 @@ as well!
enforced in our GitHub CI.
* Partial functions are to be avoided: the window manager should not
crash, so do not call `error` or `undefined`
crash, so do not call `error` or `undefined`.
* Any pure function added to the core should have QuickCheck
properties precisely defining its behavior.
@ -103,84 +106,15 @@ as well!
* New modules should identify the author, and be submitted under the
same license as xmonad (BSD3 license).
## Rebasing and Squashing Commits
## Keep rocking!
Under no circumstances should you ever merge the master branch into
your feature branch. This makes it nearly impossible to review your
changes and we *will not accept your PR* if you do this.
Instead of merging you should rebase your changes on top of the master
branch. If a core team member asks you to "rebase your changes" this
is what they are talking about.
It's also helpful to squash all of your commits so that your pull
request only contains a single commit. Again, this makes it easier to
review your changes and identify the changes later on in the Git
history.
### How to Rebase Your Changes
The goal of rebasing is to bring recent changes from the master branch
into your feature branch. This often helps resolve conflicts where
you have changed a file that also changed in a recently merged pull
request (i.e. the `CHANGES.md` file). Here is how you do that.
1. Make sure that you have a `git remote` configured for the main
repository. I like to call this remote `upstream`:
```shell
$ git remote add upstream https://github.com/xmonad/xmonad-contrib.git
```
2. Pull from upstream and rewrite your changes on top of master. For
this to work you should not have any modified files in your
working directory. Run these commands from within your feature
branch (the branch you are asking to be merged):
```shell
$ git fetch --all
$ git pull --rebase upstream master
```
3. If the rebase was successful you can now push your feature branch
back to GitHub. You need to force the push since your commits
have been rewritten and have new IDs:
```shell
$ git push --force-with-lease
```
4. Your pull request should now be conflict-free and only contain the
changes that you actually made.
### How to Squash Commits
The goal of squashing commits is to produce a clean Git history where
each pull request contains just one commit.
1. Use `git log` to see how many commits you are including in your
pull request. (If you've already submitted your pull request you
can see this in the GitHub interface.)
2. Rebase all of those commits into a single commit. Assuming you
want to squash the last four (4) commits into a single commit:
```shell
$ git rebase -i HEAD~4
```
3. Git will open your editor and display the commits you are
rebasing with the word "pick" in front of them.
4. Leave the first listed commit as "pick" and change the remaining
commits from "pick" to "squash".
5. Save the file and exit your editor. Git will create a new commit
and open your editor so you can modify the commit message.
6. If everything was successful you can push your changed history
back up to GitHub:
```shell
$ git push --force-with-lease
```
xmonad is a passion project created and maintained by the community.
We'd love for you to maintain your own contributed modules (approve
changes from other contributors, review code, etc.). However, before
we'd be comfortable adding you to the [xmonad GitHub
organization][xmonad-gh-org] we need to trust that you have sufficient
knowledge of Haskell and git; and have a way of chatting with you ([IRC,
Matrix, etc.][community]).
[hlint]: https://github.com/ndmitchell/hlint
[xmonad]: https://github.com/xmonad/xmonad
@ -191,3 +125,7 @@ each pull request contains just one commit.
[xmonad-doc-developing]: https://xmonad.github.io/xmonad-docs/xmonad-contrib/XMonad-Doc-Developing.html
[`#xmonad` IRC channel]: https://web.libera.chat/#xmonad
[matrix channel]: https://matrix.to/#/#xmonad:matrix.org
[commit-cbeams]: https://cbea.ms/git-commit/
[commit-kernel]: https://www.kernel.org/doc/html/v4.10/process/submitting-patches.html#separate-your-changes
[community]: https://xmonad.org/community.html
[xmonad-gh-org]: https://github.com/xmonad