Skip to content

Code Contribution and Maintenance Guide

Jump to bottom
Aman Sahil edited this page Apr 24, 2020 · 4 revisions

Quick Start

The project requires:

  • Qmake version >= 4.0
  • Qt version >= 5.10 with Core, Gui enabled.
  • c++11
  • doxygen v1.8.17

Resources

Code of conduct

Please follow these guidelines to create a respectful and productive enviroment for all contributors

  • Ensure you have an open mind when tackling or commenting on issues, feature requests and PR's

  • Be considerate of peoples work and effort

  • Be open to constructive criticism and do so in a polite manner

  • Please keep community first over personal opinions/preferences

  • Please refrain from using negative language, always be welcoming and inclusive

  • Ensure community standards are being met

Reporting Issues

To report a bug, use the GitHub issue tracker to create a report. Ensure that you have searched similar topics and that there are no duplicate topics pertaining to your case. Please don't use the issue tracker for support questions.

Writing a good bug report

Ensure the title is clear, short and to the point. In the body of the issue be as descriptive as possible and provide as much detail as you can. Write steps to recreate the problem you ran into and also include what behaviour you expected to see instead. Include screenshots of the issue or GIFS of you recreating the issue if possible. If you are using a pre-compiled version of the application mention the OS version and name. If you are compiling using release binaries mention the version of QT and the OS Verison and name. And finally, if you are using the QT IDE to generate binaries and run the code, try running the code in debugging mode and include the debug logs or any screenshots of any notification the debugger throws.

Template

## Description:

**QT Version**:

**OS Name and Version**:

## Steps to reproduce

## Expected Results

## Images

## Debugger log

Suggesting a feature or enhancement

To suggest a feature or enhancement use the GitHub issue tracker to create a report. Ensure that you have searched similar topics and that there are no duplicate topics pertaining to your suggestion. If it is a small enhancement to the code, simply open a pull request with details on the enhancement in the pull request description (Please follow the PR guidelines when doing so).

Writing a good suggestion

When suggesting a feature/enhancement ensure the description is clear. Include why the feature/enhancement is needed and how it would be implemented/used. If the feature/enhancement requires changes to the UI please provide if possible a GUI mockup of such an implementation.

Pull Requests

Guidelines

  • Ensure you have read the Commit guidelines and Branch guidelines subsection of this section.
  • Ensure you have followed standards in the Code Standards section
  • Ensure cross-platform compatibility for Windows, Ubuntu and Mac
  • Write a descriptive pull request title
  • If there were any UI based changes please include screenshots in the pull request description
  • If there were any changes to the flow please attach a video in the pull request description
  • Please add tests for any new methods created
  • Please add documentation for any new methods or data members
  • If there was a need to update existing tests mention why in the description
  • Ensure all tests pass before submitting your pull request
  • If you use a hack or workarounds from the internet, attach the link
  • Attach Trello link or Github issue tracker link if relevant
  • Important : Use git rebase instead of git merge to sync your branch
  • Attach the checklist below and ensure all boxes are ticked
V2

- [ ] All curly braces are on a new line for multiline code
- [ ] No unsued includes
- [ ] No unsued variables
- [ ] For variables that aren't reassigned use const
- [ ] For methods that aren't manipulating any state use const
- [ ] Used proper spacing between code
- [ ] Used QT containers where possible
- [ ] All methods are documented by Doxygen
- [ ] Removed asserts and qDebug

Template

**Description**:

**Checklist**:

V2

- [ ] All curly braces are on a new line for multiline code
- [ ] No unsued includes
- [ ] No unsued variables
- [ ] For variables that aren't reassigned use const
- [ ] For methods that aren't manipulating any state use const
- [ ] Used proper spacing between code
- [ ] Used QT containers where possible
- [ ] All methods are documented by Doxygen
- [ ] Removed asserts and qDebug

**Trello or Github issue link**:

**Images and videos**:

Commit guidelines

  • The commit message should be no more than 72 characters

  • Commits should regularly be done for single units of work (function-based instead of functionality based), do not cram too many changes into one commit

  • Capitalise the subject line

  • Ensure updates to tests are on a separate commit and follow conventions shown in below examples

    Eg for new tests: Added new tests for foo

    Eg for existing tests: Updated existing test to accommodate bar

  • Ensure updates to documentation are on a separate commit and follow convention shown in below example

    Eg: Updated docs

  • Examples of good commit messages:

    • Added method to determine the aspect ratio of an image

    • Code style refactor for bar

    • Refactor of foo method for better readability

    • Removed unused variable in bar

  • Example of bad commits:

    • Refactor

    • Fixes

    • Added image edit method

Branch guidelines

When creating a branch on the GitHub repository ensure the branch name is a short concise name which uses kebab case relative to the feature or fixes being added, with the last section of the name identifying what type of pull request it is.

Eg for features: image-resize-feature

Eg for enhancement: resize-method-enhancement

Eg for fixes: image-resize-crash-fix or unresponsive-save-button-fix

Maintaining Documentation

Doxygen is used to auto-generate the documentation. Ensure you have the correct version of doxygen installed. Documentation can be updated using the following command.

doxygen doxyfile.cfg

Guidelines

  • Ensure you have read the Documenting code subsection
  • Please add documentation for any new methods or data members
  • Ensure updates to documentation are on separate commit

Documenting code

Use the Qt style comment block to document code

  • //! - For classes, data memebers and enums
  • /*! - For member functions
  • /*!< - For enum values

Eg:

//! A nice short description of what the class is responsible for
class someClass;

//! A nice short description of what state the enum is used to identify
enum someEnum {
    SomeValue /*!< A short descrition of what the value means */
};

//! A nice short description of what information the container holds
int someValue;

/*!
 *  A nice short description of what the function does, two spaces away from the astrix
 */
void sumeFunc();

Clone this wiki locally