StarMirror/qTox
1
0
Fork 0
mirror of https://github.com/qTox/qTox.git synced 2024-03-22 14:00:36 +08:00
Code Issues Projects Releases Wiki Activity
904d5c1621
qTox/CONTRIBUTING.md

273 lines
7.7 KiB
Markdown
Raw Normal View History

Add CONTRIBUTING.md It was taken from https://github.com/qbittorrent/qBittorrent/blob/76c16e0994570205efb4a5596da8140eebfdcb51/CONTRIBUTING.md and adjusted for qTox needs. Since qBittorrent is licensed under GPLv2+, file in qTox source is covered by GPLv3+.
2015-12-31 21:18:57 +08:00
# Filing an issue
### Must read
style(Markdown): wrap all .md files at 80 characters Short lines make it easier to evaluate diffs. Fix only critical typos, like missing full stops in the middle of a sentence. Everything else left untouched.
2016-04-10 05:47:39 +08:00
* If you aren't sure, you can ask on the
[**IRC channel**](https://webchat.freenode.net/?channels=qtox) or read our
[**wiki**](https://github.com/tux3/qTox/wiki) first.
Fixed grammatical errors
2016-02-09 00:24:52 +08:00
* Do a quick **search**. Others might have already reported the issue.
Add CONTRIBUTING.md It was taken from https://github.com/qbittorrent/qBittorrent/blob/76c16e0994570205efb4a5596da8140eebfdcb51/CONTRIBUTING.md and adjusted for qTox needs. Since qBittorrent is licensed under GPLv2+, file in qTox source is covered by GPLv3+.
2015-12-31 21:18:57 +08:00
* Write in **English**!
style(Markdown): wrap all .md files at 80 characters Short lines make it easier to evaluate diffs. Fix only critical typos, like missing full stops in the middle of a sentence. Everything else left untouched.
2016-04-10 05:47:39 +08:00
* Provide **version** information (you can find version numbers in menu
`Settings → About`):
style: enhance and reformat issue template Add missing required information for new issues Redo Markdown format for a cleaner raw display Standarise requirements/terms with CONTRIBUTING.md
2016-04-08 16:04:19 +08:00
```
OS:
qTox version:
Add CONTRIBUTING.md It was taken from https://github.com/qbittorrent/qBittorrent/blob/76c16e0994570205efb4a5596da8140eebfdcb51/CONTRIBUTING.md and adjusted for qTox needs. Since qBittorrent is licensed under GPLv2+, file in qTox source is covered by GPLv3+.
2015-12-31 21:18:57 +08:00
Commit hash:
toxcore:
Qt:
style: enhance and reformat issue template Add missing required information for new issues Redo Markdown format for a cleaner raw display Standarise requirements/terms with CONTRIBUTING.md
2016-04-08 16:04:19 +08:00
```
style(Markdown): wrap all .md files at 80 characters Short lines make it easier to evaluate diffs. Fix only critical typos, like missing full stops in the middle of a sentence. Everything else left untouched.
2016-04-10 05:47:39 +08:00
* Provide **steps** to reproduce the problem, it will be easier to pinpoint the
fault.
* **Screenshots**! A screenshot is worth a thousand words. Just upload it.
[(How?)](https://help.github.com/articles/file-attachments-on-issues-and-pull-requests)
Add CONTRIBUTING.md It was taken from https://github.com/qbittorrent/qBittorrent/blob/76c16e0994570205efb4a5596da8140eebfdcb51/CONTRIBUTING.md and adjusted for qTox needs. Since qBittorrent is licensed under GPLv2+, file in qTox source is covered by GPLv3+.
2015-12-31 21:18:57 +08:00
### Good to know
style(Markdown): wrap all .md files at 80 characters Short lines make it easier to evaluate diffs. Fix only critical typos, like missing full stops in the middle of a sentence. Everything else left untouched.
2016-04-10 05:47:39 +08:00
* **Patience**. The dev team is small and resource limited. Devs have to find
time, analyze the problem and fix the issue, it all takes time. :clock3:
* If you can code, why not become a **contributor** by fixing the issue and
opening a pull request? :wink:
* Harsh words or threats won't help your situation. What's worse, your complaint
will (very likely) be **ignored**. :fearful:
Add CONTRIBUTING.md It was taken from https://github.com/qbittorrent/qBittorrent/blob/76c16e0994570205efb4a5596da8140eebfdcb51/CONTRIBUTING.md and adjusted for qTox needs. Since qBittorrent is licensed under GPLv2+, file in qTox source is covered by GPLv3+.
2015-12-31 21:18:57 +08:00
# Opening a pull request
### Must read
style: enhance and reformat issue template Add missing required information for new issues Redo Markdown format for a cleaner raw display Standarise requirements/terms with CONTRIBUTING.md
2016-04-08 16:04:19 +08:00
* Use [**commit message format**](#commit-message-format).
docs(CONTRIBUTING.md): change obsolete link
2016-04-29 02:49:02 +08:00
* Read our [**coding guidelines**](#coding-guidelines).
style(Markdown): wrap all .md files at 80 characters Short lines make it easier to evaluate diffs. Fix only critical typos, like missing full stops in the middle of a sentence. Everything else left untouched.
2016-04-10 05:47:39 +08:00
* Keep the title **short** and provide a **clear** description about what your
pull request does.
Add CONTRIBUTING.md It was taken from https://github.com/qbittorrent/qBittorrent/blob/76c16e0994570205efb4a5596da8140eebfdcb51/CONTRIBUTING.md and adjusted for qTox needs. Since qBittorrent is licensed under GPLv2+, file in qTox source is covered by GPLv3+.
2015-12-31 21:18:57 +08:00
* Provide **screenshots** for UI related changes.
style(Markdown): wrap all .md files at 80 characters Short lines make it easier to evaluate diffs. Fix only critical typos, like missing full stops in the middle of a sentence. Everything else left untouched.
2016-04-10 05:47:39 +08:00
* Keep your git commit history **clean** and **precise**. Commits like
`xxx fixup` should not appear.
docs(CONTRIBUTING.md): make more explicit what commit message needs By clearly stating what commit message needs to have. Should help with commit messages that aren't really clear.
2016-07-23 15:39:02 +08:00
* Commit message should state not only what has been changed, but also why a
change is needed.
style(Markdown): wrap all .md files at 80 characters Short lines make it easier to evaluate diffs. Fix only critical typos, like missing full stops in the middle of a sentence. Everything else left untouched.
2016-04-10 05:47:39 +08:00
* If your commit fixes a reported issue (for example #4134), add the following
message to the commit `Fixes #4134.`.
[Here is an example](https://github.com/tux3/qTox/commit/87160526d5bafcee7869d6741a06045e13d731d5).
Add CONTRIBUTING.md It was taken from https://github.com/qbittorrent/qBittorrent/blob/76c16e0994570205efb4a5596da8140eebfdcb51/CONTRIBUTING.md and adjusted for qTox needs. Since qBittorrent is licensed under GPLv2+, file in qTox source is covered by GPLv3+.
2015-12-31 21:18:57 +08:00
### Good to know
style(Markdown): wrap all .md files at 80 characters Short lines make it easier to evaluate diffs. Fix only critical typos, like missing full stops in the middle of a sentence. Everything else left untouched.
2016-04-10 05:47:39 +08:00
* **Search** the pull request history! Others might have already implemented
your idea and it could be waiting to be merged (or have been rejected
already). Save your precious time by doing a search first.
* When resolving merge conflicts, do `git rebase <target_branch_name>`, don't do
`git pull`. Then you can start fixing the conflicts.
[Here is a good explanation](https://www.atlassian.com/git/tutorials/merging-vs-rebasing).
Add CONTRIBUTING.md It was taken from https://github.com/qbittorrent/qBittorrent/blob/76c16e0994570205efb4a5596da8140eebfdcb51/CONTRIBUTING.md and adjusted for qTox needs. Since qBittorrent is licensed under GPLv2+, file in qTox source is covered by GPLv3+.
2015-12-31 21:18:57 +08:00
docs(CONTRIBUTING.md): add section about commit message format With a proper, (not yet) enforced commit message format qTox would get both clean commit messages and automatically generated changelog. In regard to #2887. Content of the commit taken from `CONTRIBUTING.md` @ https://github.com/zetok/tox/tree/96e2cec95a33f83a28716eea1cef71c5e97ce300 and adjusted for qTox needs.
2016-03-28 22:49:44 +08:00
## <a name="commit"></a> Git Commit Guidelines
We have very precise rules over how our git commit messages can be formatted.
This leads to **more readable messages** that are easy to follow when looking
through the **project history**. But also, we use the git commit messages to
style(Markdown): wrap all .md files at 80 characters Short lines make it easier to evaluate diffs. Fix only critical typos, like missing full stops in the middle of a sentence. Everything else left untouched.
2016-04-10 05:47:39 +08:00
**generate the qTox change log** using
[clog-cli](https://github.com/clog-tool/clog-cli).
docs(CONTRIBUTING.md): add section about commit message format With a proper, (not yet) enforced commit message format qTox would get both clean commit messages and automatically generated changelog. In regard to #2887. Content of the commit taken from `CONTRIBUTING.md` @ https://github.com/zetok/tox/tree/96e2cec95a33f83a28716eea1cef71c5e97ce300 and adjusted for qTox needs.
2016-03-28 22:49:44 +08:00
### Commit Message Format
style(Markdown): wrap all .md files at 80 characters Short lines make it easier to evaluate diffs. Fix only critical typos, like missing full stops in the middle of a sentence. Everything else left untouched.
2016-04-10 05:47:39 +08:00
Each commit message consists of a **header** and a **body**. The header has a
special format that includes a **type**, a **scope** and a **subject**:
docs(CONTRIBUTING.md): add section about commit message format With a proper, (not yet) enforced commit message format qTox would get both clean commit messages and automatically generated changelog. In regard to #2887. Content of the commit taken from `CONTRIBUTING.md` @ https://github.com/zetok/tox/tree/96e2cec95a33f83a28716eea1cef71c5e97ce300 and adjusted for qTox needs.
2016-03-28 22:49:44 +08:00
```
<type>(<scope>): <subject>
<BLANK LINE>
<body>
```
style(Markdown): wrap all .md files at 80 characters Short lines make it easier to evaluate diffs. Fix only critical typos, like missing full stops in the middle of a sentence. Everything else left untouched.
2016-04-10 05:47:39 +08:00
The **header** is mandatory and the **body** is optional. The **scope** of the
header is also optional.
docs(CONTRIBUTING.md): add section about commit message format With a proper, (not yet) enforced commit message format qTox would get both clean commit messages and automatically generated changelog. In regard to #2887. Content of the commit taken from `CONTRIBUTING.md` @ https://github.com/zetok/tox/tree/96e2cec95a33f83a28716eea1cef71c5e97ce300 and adjusted for qTox needs.
2016-03-28 22:49:44 +08:00
docs: edit and reorganize Git Commit Guidelines Reorganize the Git Commit Guidelines title hierarchy. Various content edits in the Git Commit Guidelines section: - Remove the footer section and merge its contents with the body - Add revert to the list of possible header types - Change the maximum line length for header and body - Add instructions about the body's elements order
2016-04-03 07:31:52 +08:00
### Header
The header must be a short (72 characters or less) summary of the changes made.
docs(CONTRIBUTING.md): add section about commit message format With a proper, (not yet) enforced commit message format qTox would get both clean commit messages and automatically generated changelog. In regard to #2887. Content of the commit taken from `CONTRIBUTING.md` @ https://github.com/zetok/tox/tree/96e2cec95a33f83a28716eea1cef71c5e97ce300 and adjusted for qTox needs.
2016-03-28 22:49:44 +08:00
docs: edit and reorganize Git Commit Guidelines Reorganize the Git Commit Guidelines title hierarchy. Various content edits in the Git Commit Guidelines section: - Remove the footer section and merge its contents with the body - Add revert to the list of possible header types - Change the maximum line length for header and body - Add instructions about the body's elements order
2016-04-03 07:31:52 +08:00
#### Type
docs(CONTRIBUTING.md): add section about commit message format With a proper, (not yet) enforced commit message format qTox would get both clean commit messages and automatically generated changelog. In regard to #2887. Content of the commit taken from `CONTRIBUTING.md` @ https://github.com/zetok/tox/tree/96e2cec95a33f83a28716eea1cef71c5e97ce300 and adjusted for qTox needs.
2016-03-28 22:49:44 +08:00
Must be one of the following:
* **feat**: A new feature
* **fix**: A bug fix
* **docs**: Documentation only changes
style(Markdown): wrap all .md files at 80 characters Short lines make it easier to evaluate diffs. Fix only critical typos, like missing full stops in the middle of a sentence. Everything else left untouched.
2016-04-10 05:47:39 +08:00
* **style**: Changes that do not affect the meaning of the code (white-space,
docs(CONTRIBUTING.md): change type descriptions for less confusion
2016-07-03 17:54:03 +08:00
formatting, etc), but change the style to a more appropriate one
fix(doc): CONTRIBUTING.md typos
2016-07-03 19:30:11 +08:00
* **refactor**: A code change that only improves code readability
and reduces complexity, without changing any functionality
docs(CONTRIBUTING.md): add section about commit message format With a proper, (not yet) enforced commit message format qTox would get both clean commit messages and automatically generated changelog. In regard to #2887. Content of the commit taken from `CONTRIBUTING.md` @ https://github.com/zetok/tox/tree/96e2cec95a33f83a28716eea1cef71c5e97ce300 and adjusted for qTox needs.
2016-03-28 22:49:44 +08:00
* **perf**: A code change that improves performance
docs: edit and reorganize Git Commit Guidelines Reorganize the Git Commit Guidelines title hierarchy. Various content edits in the Git Commit Guidelines section: - Remove the footer section and merge its contents with the body - Add revert to the list of possible header types - Change the maximum line length for header and body - Add instructions about the body's elements order
2016-04-03 07:31:52 +08:00
* **revert**: Reverts a previous commit
docs(CONTRIBUTING.md): add section about commit message format With a proper, (not yet) enforced commit message format qTox would get both clean commit messages and automatically generated changelog. In regard to #2887. Content of the commit taken from `CONTRIBUTING.md` @ https://github.com/zetok/tox/tree/96e2cec95a33f83a28716eea1cef71c5e97ce300 and adjusted for qTox needs.
2016-03-28 22:49:44 +08:00
* **test**: Adding missing tests
style(Markdown): wrap all .md files at 80 characters Short lines make it easier to evaluate diffs. Fix only critical typos, like missing full stops in the middle of a sentence. Everything else left untouched.
2016-04-10 05:47:39 +08:00
* **chore**: Changes to the build process or auxiliary tools and libraries such
as documentation generation
docs(CONTRIBUTING.md): add section about commit message format With a proper, (not yet) enforced commit message format qTox would get both clean commit messages and automatically generated changelog. In regard to #2887. Content of the commit taken from `CONTRIBUTING.md` @ https://github.com/zetok/tox/tree/96e2cec95a33f83a28716eea1cef71c5e97ce300 and adjusted for qTox needs.
2016-03-28 22:49:44 +08:00
docs: edit and reorganize Git Commit Guidelines Reorganize the Git Commit Guidelines title hierarchy. Various content edits in the Git Commit Guidelines section: - Remove the footer section and merge its contents with the body - Add revert to the list of possible header types - Change the maximum line length for header and body - Add instructions about the body's elements order
2016-04-03 07:31:52 +08:00
##### Revert
style(Markdown): wrap all .md files at 80 characters Short lines make it easier to evaluate diffs. Fix only critical typos, like missing full stops in the middle of a sentence. Everything else left untouched.
2016-04-10 05:47:39 +08:00
If the commit reverts a previous commit, it should begin with `revert: `,
followed by the header of the reverted commit. In the body it should say:
`Revert commit <hash>.`, where the hash is the SHA of the commit being reverted.
docs: edit and reorganize Git Commit Guidelines Reorganize the Git Commit Guidelines title hierarchy. Various content edits in the Git Commit Guidelines section: - Remove the footer section and merge its contents with the body - Add revert to the list of possible header types - Change the maximum line length for header and body - Add instructions about the body's elements order
2016-04-03 07:31:52 +08:00
#### Scope
style(Markdown): wrap all .md files at 80 characters Short lines make it easier to evaluate diffs. Fix only critical typos, like missing full stops in the middle of a sentence. Everything else left untouched.
2016-04-10 05:47:39 +08:00
The scope could be anything specifying place of the commit change. For example
`$location`, `$browser`, `$compile`, `$rootScope`, `ngHref`, `ngClick`,
`ngView`, etc.
docs(CONTRIBUTING.md): add section about commit message format With a proper, (not yet) enforced commit message format qTox would get both clean commit messages and automatically generated changelog. In regard to #2887. Content of the commit taken from `CONTRIBUTING.md` @ https://github.com/zetok/tox/tree/96e2cec95a33f83a28716eea1cef71c5e97ce300 and adjusted for qTox needs.
2016-03-28 22:49:44 +08:00
docs: edit and reorganize Git Commit Guidelines Reorganize the Git Commit Guidelines title hierarchy. Various content edits in the Git Commit Guidelines section: - Remove the footer section and merge its contents with the body - Add revert to the list of possible header types - Change the maximum line length for header and body - Add instructions about the body's elements order
2016-04-03 07:31:52 +08:00
#### Subject
docs(CONTRIBUTING.md): add section about commit message format With a proper, (not yet) enforced commit message format qTox would get both clean commit messages and automatically generated changelog. In regard to #2887. Content of the commit taken from `CONTRIBUTING.md` @ https://github.com/zetok/tox/tree/96e2cec95a33f83a28716eea1cef71c5e97ce300 and adjusted for qTox needs.
2016-03-28 22:49:44 +08:00
The subject contains succinct description of the change:
* use the imperative, present tense: "change" not "changed" nor "changes"
* don't capitalize first letter
* no dot (.) at the end
style(Markdown): wrap all .md files at 80 characters Short lines make it easier to evaluate diffs. Fix only critical typos, like missing full stops in the middle of a sentence. Everything else left untouched.
2016-04-10 05:47:39 +08:00
A properly formed git commit subject line should always be able to complete the
following sentence:
docs: edit and reorganize Git Commit Guidelines Reorganize the Git Commit Guidelines title hierarchy. Various content edits in the Git Commit Guidelines section: - Remove the footer section and merge its contents with the body - Add revert to the list of possible header types - Change the maximum line length for header and body - Add instructions about the body's elements order
2016-04-03 07:31:52 +08:00
> If applied, this commit will ___your subject line here___
docs(CONTRIBUTING.md): add section about commit message format With a proper, (not yet) enforced commit message format qTox would get both clean commit messages and automatically generated changelog. In regard to #2887. Content of the commit taken from `CONTRIBUTING.md` @ https://github.com/zetok/tox/tree/96e2cec95a33f83a28716eea1cef71c5e97ce300 and adjusted for qTox needs.
2016-03-28 22:49:44 +08:00
### Body
style(Markdown): wrap all .md files at 80 characters Short lines make it easier to evaluate diffs. Fix only critical typos, like missing full stops in the middle of a sentence. Everything else left untouched.
2016-04-10 05:47:39 +08:00
Wrap the body at 72 characters whenever possible (for example, don't modify long
links to follow this rule). Just as in the **subject**, use the imperative,
present tense: "change" not "changed" nor "changes". The body should include the
motivation for the change and contrast this with previous behavior.
docs(CONTRIBUTING.md): add section about commit message format With a proper, (not yet) enforced commit message format qTox would get both clean commit messages and automatically generated changelog. In regard to #2887. Content of the commit taken from `CONTRIBUTING.md` @ https://github.com/zetok/tox/tree/96e2cec95a33f83a28716eea1cef71c5e97ce300 and adjusted for qTox needs.
2016-03-28 22:49:44 +08:00
docs: edit and reorganize Git Commit Guidelines Reorganize the Git Commit Guidelines title hierarchy. Various content edits in the Git Commit Guidelines section: - Remove the footer section and merge its contents with the body - Add revert to the list of possible header types - Change the maximum line length for header and body - Add instructions about the body's elements order
2016-04-03 07:31:52 +08:00
The body contains (in order of appearance):
* A detailed **description** of the committed changes.
style(Markdown): wrap all .md files at 80 characters Short lines make it easier to evaluate diffs. Fix only critical typos, like missing full stops in the middle of a sentence. Everything else left untouched.
2016-04-10 05:47:39 +08:00
* References to GitHub issues that the commit **closes** (e.g., `Closes #000` or
`Fixes #000`).
docs: edit and reorganize Git Commit Guidelines Reorganize the Git Commit Guidelines title hierarchy. Various content edits in the Git Commit Guidelines section: - Remove the footer section and merge its contents with the body - Add revert to the list of possible header types - Change the maximum line length for header and body - Add instructions about the body's elements order
2016-04-03 07:31:52 +08:00
* Any **breaking changes**.
Include every section of the body that is relevant for your commit.
docs(CONTRIBUTING.md): add section about commit message format With a proper, (not yet) enforced commit message format qTox would get both clean commit messages and automatically generated changelog. In regard to #2887. Content of the commit taken from `CONTRIBUTING.md` @ https://github.com/zetok/tox/tree/96e2cec95a33f83a28716eea1cef71c5e97ce300 and adjusted for qTox needs.
2016-03-28 22:49:44 +08:00
style(Markdown): wrap all .md files at 80 characters Short lines make it easier to evaluate diffs. Fix only critical typos, like missing full stops in the middle of a sentence. Everything else left untouched.
2016-04-10 05:47:39 +08:00
**Breaking changes** should start with the phrase `BREAKING CHANGE:` with a
space or two newlines. The rest of the commit message is then used for this.
docs(CONTRIBUTING.md): add coding guidelines (moved from wiki)
2016-04-16 13:51:03 +08:00
## Git config
*Not a requirement, just a friendly tip. :wink:*
It's nice when commits are being GPG-signed. Github has a few articles about
configuring & signing.
https://help.github.com/articles/signing-commits-using-gpg/
And *tl;dr* version:
```
gpg --gen-key
gpg --send-keys <your generated key ID>
git config --global commit.gpgsign true
```
# Coding Guidelines
Use `C++11`.
## Coding style
```C++
function()
{
1st_line;
2nd_line;
}
// if / while / for / switch
if ()
1_line;
else if ()
just_one_line;
else
each_condition;
// ↑ note space between last line of conditional code, and code outside of condition
if ()
{
1_line;
}
else if ()
{
what_if;
i_told_you;
}
else
{
that_there_are;
more_lines;
}
QObject* asterisksGoWithTheType;
uint8_t* array = new uint8_t[count];
// camelCase for variables, CamelCase for classes
QObject notToMentionThatWeUseCamelCase;
```
E.g. https://github.com/tux3/qTox/blob/master/src/misc/flowlayout.cpp
docs(CONTRIBUTING.md): Added documntation block
2016-07-27 06:21:47 +08:00
## Documentaion
If you added a new function, also add a doxygen comment before the implementation.
If you changed an old function, make sure the doxygen comment is still correct.
If it doesn't exist add it.
Don't put docs in .h files, if there is a corresponding .cpp file.
### Documentation style
```C++
/*...license info...*/
#include "blabla.h"
/**
I can be briefly described as well!
*/
static void method()
{
// I'm just a little example.
}
/**
@class OurClass
@brief Exists for some reason...!?
Longer description
*/
/**
@enum OurClass::OurEnum
@brief The brief description line.
@var EnumValue1
means something
@var EnumValue2
means something else
Optional long description
*/
/**
@fn OurClass::somethingHappened(const QString &happened)
@param[in] happened tells what has happened...
@brief This signal is emitted when something has happened in the class.
Here's an optional longer description of what the signal additionally does.
*/
```
docs(CONTRIBUTING.md): add coding guidelines (moved from wiki)
2016-04-16 13:51:03 +08:00
## No translatable HTML tags
Do not put HTML in UI files, or inside `tr()`. Instead, you can put put it in
C++ code in the following way, to make only user-facing text translatable:
```C++
someWidget->setTooltip(
QStringLiteral("<html><!-- some HTML text -->") + tr("Translatable text…") +
QStringLiteral("</html>");
```
## Limitations
### Filesystem
Windows' unbeaten beauty and clarity:
https://msdn.microsoft.com/en-us/library/windows/desktop/aa365247%28v=vs.85%29.aspx
Symbols that should be forbidden for filenames under Windows:
`<` `>` `:` `"` `/` `\` `|` `?` `*`
Reference in New Issue Copy Permalink