sample-hive/CONTRIBUTING.org

Contributing to SampleHive

• Table Of Contents
• Contributing to SampleHive
  • What should I know before I get started?
  • How Can I Contribute?
    • Reporting Bugs
      • Before Submitting A Bug Report
      • How Do I Submit A (Good) Bug Report?
    • Suggesting Enhancements
      • Before Submitting An Enhancement Suggestion
      • How Do I Submit A (Good) Enhancement Suggestion?
    • Pull Requests
  • Styleguides
    • Git Commit Messages
    • C++ Styleguide
  • Additional Notes
    • Issue and Pull Request Labels
      • Issue Labels
      • Pull Request Labels

Table Of Contents   toc

• Contributing to SampleHive

  • What should I know before I get started?
  • How Can I Contribute?
  • Styleguides
  • Additional Notes

Contributing to SampleHive

First off, thanks for taking the time to contribute!

The following is a set of guidelines for contributing to SampleHive, which is hosted on GitLab. These are mostly guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request.

What should I know before I get started?

How Can I Contribute?

Reporting Bugs

This section guides you through submitting a bug report for SampleHive. Following these guidelines helps me and the community understand your report, reproduce the behavior, and find related reports.

Before creating bug reports, please check this list as you might find out that you don't need to create one. When you are creating a bug report, please include as many details as possible. Fill out the required template, the information it asks for helps us resolve issues faster.

Note: If you find a Closed issue that seems like it is the same thing that you're experiencing, do not open a new issue, instead re-open the the old one, and add a comment there, stating any additional details you want to add.

Before Submitting A Bug Report

• Perform a cursory search to see if the bug has already been reported. If it has, add a comment to the existing issue instead of opening a new one.

How Do I Submit A (Good) Bug Report?

Explain the problem and include additional details to help me reproduce the problem:

• Use a clear and descriptive title for the issue to identify the problem.
• Describe the exact steps which reproduce the problem in as many details as possible.
• Describe the behavior you observed after following the steps and point out what exactly is the problem with that behavior.
• Explain which behavior you expected to see instead and why.
• Include screenshots and animated GIFs which show you following the described steps and clearly demonstrate the problem. You can record the GIF using Peek
• If you're reporting that SampleHive crashed, include a crash report with a stack trace from the operating system.

Include details about your configuration and environment:

• Which version of SampleHive are you using? You can get the exact version by opening up the about dialog inside the application or you can run SampleHive --version in your terminal.
• What's the name and version of the Operating System you're using?

Suggesting Enhancements

This section guides you through submitting an enhancement suggestion for SampleHive, including completely new features and minor improvements to existing functionality. Following these guidelines helps me and the community understand your suggestion and find related suggestions.

Before creating enhancement suggestions, please check this list as you might find out that you don't need to create one. When you are creating an enhancement suggestion, please include as many details as possible. Fill out the required template, including the steps that you imagine you would take if the feature you're requesting existed.

Before Submitting An Enhancement Suggestion

• Perform a cursory search to see if the enhancement has already been suggested. If it has, add a comment to the existing issue instead of opening a new one.

How Do I Submit A (Good) Enhancement Suggestion?

Enhancement suggestions are tracked as GitLab issues. Create an issue and provide the following information:

• Use a clear and descriptive title for the issue to identify the suggestion.
• Provide a step-by-step description of the suggested enhancement in as many details as possible.
• Provide specific examples to demonstrate the steps. Include copy/pasteable snippets which you use in those examples, as Markdown code blocks.
• Describe the current behavior and explain which behavior you expected to see instead and why.
• Include screenshots and animated GIFs which help you demonstrate the steps or point out the part of SampleHive which the suggestion is related to. You can use Peek to record GIFs.
• Explain why this enhancement would be useful to most SampleHive users.
• List some other sample manager/browsers or similar applications where this enhancement exists.
• Specify which version of SampleHive you're using. You can get the exact version by opening up the about dialog inside the application or you can run SampleHive --version in your terminal.
• Specify the name and version of the Operating System you're using.

Pull Requests

Please follow these steps to have your contribution considered by the maintainers:

1. Follow the styleguides

Styleguides

Git Commit Messages

• Use the present tense ("Add feature" not "Added feature")

C++ Styleguide

• Formatting the body, spacing and where to put the reference or pointer symbol

  // Use this
  int Function(int* param, std::string& anotherParam)
  {
      // 4 spaces
  }

  // Instead of
  int function ( int *param, std::string &another_param ) {
      // Tabs
  }

• Using if else for while or any of the similar statements

  • You can leave the {} if there is only a single line of code after the statements

  // Use this:
  if (condition)
  {
      // some code here
  }
  else
  {
      // some code here
  }

  // Instead of
  if( condition ) {
      // some code here
  }
  else {
      // some code here
  }

• Variable names

  // Member variables
  int m_SomeVar;    // for stack allocated
  int* m_pSomeVar;  // for heap allocated
  bool m_bSomeVar;  // for booleans

  // Local variables
  int some_var;   // for stack allocated
  int* someVar;   // for heap allocated
  bool some_var;  // for booleans

• Classes and structs

  // Use this
  class cMyClass : public cSomeOtherClass
  {
      public:
          MyClass();
          ~MyClass();
      private:
          // private stuff
  };

  // Instead of
  class myClass : public someOtherClass {
  public:
      MyClass();
      ~MyClass();
  private:
      // private stuff
  };

Additional Notes

Issue and Pull Request Labels

This section lists the labels I use to help me track and manage issues and pull requests.

Issue Labels

Label name	Description
Enhancement	Issues related to improving the project in some way.
Bug	Confirmed bugs or reports that are very likely to be bugs.
Question	Questions more than bug reports or feature requests (e.g. how do I do X).
Feedback	General feedback more than bug reports or feature requests.
Help wanted	Issues about user(s) needing help.
More information needed	More information needs to be collected about these problems or feature requests (e.g. steps to reproduce).
Needs reproduction	Likely bugs, but haven't been reliably reproduced.
Duplicate	Issues which are duplicates of other issues, i.e. they have been reported before.

Pull Request Labels

Label name	Description
Work in progress	Pull requests which are still being worked on, more changes will follow.
Needs review	Pull requests which need code review, and approval from maintainers.
Under review	Pull requests being reviewed by maintainers.
Requires changes	Pull requests which need to be updated based on review comments and then reviewed again.
Needs testing	Pull requests which need manual testing.