Contributing code to KVIrc's repositories

Introduction

KVIrc and related projects (KVIrc website, KVIrc themes and KVIrc scripts) now all use GitHub for development, i.e. for source maintenance, pull requests and the review of such code.
Not familiar with Git? Start by looking at GitHub's collaborating pages.

The pull request process is important, especially the code submission part, KVIrc uses the automatic travis and AppVeyor build systems to compile the pull request and allows the person(s) involved the time to make any improvements or fix any issues arising before the pr is merged into the main source tree. It also allows any interested KVIrc development Team members the opportunity to provide feedback and guidance where needed.

General guidelines for creating pull requests:

• Create topic branches. Don't ask us to pull from your master branch.
• One pull request per feature. If you want to do more than one thing, send multiple pull requests.
• Send coherent history. Make sure each individual commit message in your pull request is meaningful.
  If you had to make multiple intermediate commits while developing, please squash them before sending them to us.
  In the end before merging you may be asked to squash your commit even some more.

Try to follow these guidelines; it's the best way to get your work included in the project!

• Click to fork the application repo.
• Click to fork the themes repo.
• Click to fork the scripts repo.
• Click to fork the website repo.
• Configure the remote.

---

Clone your fork of your chosen project repo you did above into the current directory in terminal.

# the example below uses the main repo, please adapt it to match the repo you have forked.
$ git clone git@github.com:<your GitHub username>/KVIrc.git my-kvirc
# Navigate to the newly cloned directory
$ cd my-kvirc 
# Assign the original repo to a remote called e.g. "upstream"
$ git remote add upstream https://github.com/kvirc/KVIrc.git

If you cloned/forked a while ago, get the latest changes from upstream:

# Make sure you are on your 'master' branch
$ git checkout master
# Fetch upstream changes and rebase
$ git pull --rebase upstream master
# Push those changes to GitHub
$ git push -f

Create a new topic branch to contain your feature, change, or fix:

$ git checkout -b <topic-branch-name>

Commit your changes in logical chunks, or your pull request is unlikely to be merged into the main project.

Use Git's interactive rebase feature to tidy up your commits before making them public.

Push your topic branch up to your fork:

$ git push origin <topic-branch-name>

Open a pull request with a clear title and description.

If your revise your pull request or need to keep it synced/rebased with upstream do:

# Fetch upstream changes and rebase and push changes automatically updating the pull request.
$ git pull --rebase upstream master
# Resolve any conflicts, then push those changes to your open PR
$ git push -f

KVIrc Style Tips and Guidelines

Guidelines

When in doubt or in cases not covered below please consult the guidelines outlined in this section.

• For capitalization guidelines see: https://techbase.kde.org/Projects/Usability/HIG/Capitalization
• For tooltip guidelines see: https://techbase.kde.org/Projects/Usability/HIG/Tooltip
• For usability and style guidelines see: https://techbase.kde.org/Projects/Usability/HIG

Note: We refer to the KDE guidelines, this is mostly out of convenience (because writing our own takes time).

Dialog Windows

• Titles should follow the capitalization guidelines above e.g. Choose a Script File, not Choose a script file.
• For any non-modal dialogs (config dialogs, etc.), the name should have * - KVIrc* at the end. e.g. User Registration Wizard - KVIrc This also applies to wizards and file selection dialogs.
• Define a title text that reflects the dialog type / message being conveyed, avoid vague titles.

Menu Bars

• Menus have specific locations in menu bars, see the style guide above.

Menus

• Menu item(s) test should follow the capitalization guidelines above e.g. An Item, not An item.

• Common items are:

  • Cu&t
  • &Copy
  • &Paste
  • Clear
  • &Open...
  • &Save As...

• Items that open a dialog or otherwise require confirmation or additional information should have ellipses (...) immediately following their text with no spaces.

Selector Widgets

• Bool selector labels should follow the capitalization guidelines above, e.g. Enable debug output.
• String/file path/integer selectors should have labels with a colon ":" appended at the end, e.g. Comment:.
• QGroupBox text header should follow the capitalization guidelines above, e.g. Use Filtering For.
• Config selector tooltips sentences should terminate with a fullstop (period). Use formatting like
  except for separating sections.

Buttons

• Button text should also follow the capitalization guidelines above, e.g. A Button, not A button.

• Common labels are:

  • &OK
  • &Apply
  • Cancel
  • &New
  • &Add...
  • Re&move
  • &Close
  • &Browse...

• Button QToolTips should be a description of its function, and end with a fullstop (period) like: Accept all changes, and close this dialog. Kill the current user. (use singular tense verb i.e. Kill, not Kills)

• If the button has no text (i.e. KVIrc's existing server dialog), the tooltip should be the Label text however tooltip should follow the capitalization guidelines above.

• Tooltips that contain a header label, can contain <center><center> formatting, try to be consistent with the current style of similar dialogs.

• Tooltips main text should be always left aligned, make use of newlines (/n) or line breaks (<br>) type formatting to improve sentence flow.

• Buttons are best placed in a QHBox.

• Try to keep button names short and concise.