summaryrefslogtreecommitdiffhomepage
path: root/contributing.org
blob: b94392e94b286894ea860cefabdfa4798756aeec (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
#+title: Contributing to xmobar

Want to contribute to xmobar? You've come to the right place! This
document will help guide you in this endeavour.

In case you want to make any non-trivial change to xmobar, it's always
best to talk with the community first. Currently the best way to do that
is to [[https://github.com/jaor/xmobar/issues/new][create an issue]] on GitHub. There, you can talk through the
problems you are having, as well as the proposed solution.

*** Making the change

    It's best to create a separate branch in your clone of the [[https://github.com/jaor/xmobar/][xmobar
    repo]] and then push this branch to your fork.

    If your pull request undergoes several iterations and =master= has
    changed in the meantime, you may be asked to rebase on top of it;
    in this case please don't merge any branches, but actually rebase!
    This is a very nifty feature that =git= offers in order to remain a
    clean history.

    Give your commits descriptive names!  Further, it's also highly
    recommended to add a description of /why/ you made a certain change.
    The syntax for this is *commit message*, blank line, *more
    description*.  For example:

    #+begin_src shell
      Commit Message (max. 50 characters)

      Some more useful information of why this change was made;
      possibly how it connects with other commits in this same pr
      (wrapped at 72 characters).
     #+end_src

*** Opening a pull request

    Once you have pushed the branch to your fork, making a pull
    request is as easy as visiting that branch; GitHub will then even
    prompt you for it!

    Please include the following information in the description of
    your pull request:

    - Does your pull request close, or is related to, any existing
      issues?
    - What does your pull request do?  If you add a new feature, an
      example of how you would use it would be most appreciated.
    - A brief summary of how your commits fit together to achieve this
      (if necessary).

    Please also remember to update the =changelog.md= file, as well as
    any other documentation that your pull request touches upon.  For
    example, if you add a new plugin (see [[./doc/write-your-own-plugin.org][here]] for more information)
    you should update the [[./doc/plugins.org][plugins documentation]].