-
Notifications
You must be signed in to change notification settings - Fork 6
Contributing
Before you can contribute, you must fork the repo that you wish to contribute to. GitHub already has great docs on how to fork a repo, make a modification, and create a pull request. If you are not familiar with this process, please read the following before continuing:
https://help.github.com/articles/fork-a-repo
https://help.github.com/articles/using-pull-requests
This project provides multiple methods for asking other community members questions about the project. All questions are welcome, but prior to asking a question, please ensure that existing documentation and / or previous Q&As have not already answered your question prior to submission.
Bug Tracking:
https://github.com/QtMark/qmjson/issues
Mailing List:
https://groups.google.com/forum/#!forum/qtmark
IRC:
server: chat.freenode.net (freenode)
port: 6667
channel: #qtmark
Feature requests are always welcome as they help to drive the creation of future roadmaps by the community. Please submit all feature requests to the mailing list with “Feature Request:” prepended to the message’s title. Doing so provides a means for community members to filter and comment on the feature requests, ask questions, and provide input.
Mailing List:
https://groups.google.com/forum/#!forum/qtmark
If a feature request already exists, please use the existing feature request message, and add a “+1” comment to show your desire for the feature. Features requests with higher community support are more likely to be added to the roadmap.
Please do not add feature requests to the issue tracker. If you plan to implement the feature, please read the documentation on how to submit a Request for Comments (RFC).
All issues should be submitted to the following issue tracker:
Bug Tracking:
https://github.com/QtMark/qmjson/issues
When submitting an issue, please include the following documentation:
- Title
- Brief description of the issue
- Instructions for how to reproduce the issue
- Version information (or commit hash)
- Environment information (distribution, supporting library information, compiler, hardware)
- Console logs (if applicable)
- Backtrace logs (if applicable)
Prior to submitting changes to the project, a Request for Comments (RFC) is highly advised. An RFC provides the community with an opportunity to provide feedback prior to submission. The submitter should view the RFC as a chance to gain community support early, reducing the likelihood of pushback during submission.
All RFCs should be submitted to the project’s mailing list with “RFC:” prepended to the message’s title. Doing so provides a means for community members to filter and comment on the RFC, ask questions, and provide input.
Mailing List:
https://groups.google.com/forum/#!forum/qtmark
Although an RFC can take on any format, please ensure that an RFC includes the following:
- Title
- TL;DR (summary)
- Detailed description
- Impact on project
- Risks
- Proposed API changes (if applicable)
- Proposed documentation changes (if applicable)
- Proposed testing changes (if applicable)
Although an RFC should contain as much information as possible to reduce the number of questions likely to be asked by the community, it should also be as brief as possible. RFCs that are too long will likely see limited community involvement, resulting in a higher risk of pushback during the submission of any proposed changes.
All commits to the project should have the following commit format. The information used in this commit format provides the community with a means to create the project’s changelog, as well as identify what each commit addresses.
- Title (50 characters or less)
- Empty line
- Description (wrapped to 72 characters per line)
- Empty line
- [ISSUE]: link (if applicable)
- [RFC]: link (if applicable)
- Empty line
- Sign-off
For Example:
Added new API XYZ
The library was missing the ability to do blah, and as a
result, blah was not possible. The following commit adds
XYZ to the project providing the ability to:
- Do blah blah
- And blah
- As well as blah
The following blah was added to the unit tests to validate
that this new API works as intended.
[RFC]: link
Signed-off-by: John Smith <[email protected]>
The following defines how the source code for this project is formatted. Not all of the source formatting guidelines are documented, as some of these can be identified during code reviews prior to commiting pull requests, but the vast majority of the guidelines are provided.
This project uses Astyle 2.05.1 to format the source code, and the project provides a configuration file (astyle.conf) that should be used.
Prior to submitting changes to the project, all source code should be run through Astyle to verify that the proper formatting rules are applied.
With the exception of API documentation, in-body comments are almost never kept up-to-date and some developers simply refuse to write them. Instead of forcing developers to comment, this project asks that in-body comments are removed prior to submission, except comments that explain source code that was created via trial and error, or from a document / specification. If trial and error was used to create the source code, please explain each trial, and why the resulting source code was kept. For source code that adheres to a specification or document, please reference the document, it’s version number, and the location in the document that the source code implements.
Since in-body comments should be kept to a minimum, source code should be self documenting. For this reason, code that is difficult to follow, cryptic, or otherwise overly complicated will not be accepted by the community.
For “c” code, use the following:
/* Single Line Comment */
/*
* Block Comment
*/
For “cpp” code, use the following:
// Single Line Comment
//
// Block Comment
//
All filenames for this project should be written in snake case. Code is written using Camel Case. Macros should be written in screaming snake case. Please see the following for an example:
All functions should be documented using Doxygen style comment blocks. Each comment block should define the following:
- All parameters and their expected values
- Return value (if applicable)
- Error cases
- Notes (if applicable)
Doxygen comment blocks should be added to the function implementation, and not it’s definition (i.e. to the .c/.cpp and not the .h). If the function being commented is a public function, an example of it’s use should also be included.
All doxygen comment blocks should adhere to the comment guidelines defined in the governance documentation. Since comments are kept to a minimum, the function’s comment block is a great place to put notes about the function’s implementation. For more information about Doxygen, please see:
Any changes to the project that impact how the project is compiled, installed, or used should also include updates to the associated documentation.
Major tags will be managed by the community, and signify milestones in the project’s roadmap. It is up to the community members to maintain major tags, and there are currently no guarantees on the life-time of a tagged version of this project.
At any point in time, a community member can request a minor tagged version of the project via an RFC. Minor tags are managed by the community member(s) that requested the tag. The request should include:
- What to tag (git hash)
- Who’s requesting the tag
- How long the community member(s) plan to maintain the tag
- Level of testing being applied to the tag
- Supported configurations
Since more than one organization could be basing their products off of this project, minor tags provide an organization with a means to baseline the project, and provide others with some of the maintenance and stability the organization is likely to provide. The alternative would be the organization maintains an internal, stable fork of the project, that others cannot benefit from.
The goal of the roadmap is to provide the community with short term, and long term milestones. It provides community members with a clear direction for where the project is going, and what is to be expected in the future.
Any community member can propose changes to the project’s roadmap including the addition of individual tasks and project milestones. Changes to the roadmap should be presented to the community by submitting an RFC. The RFC provides the rest of the community an opportunity to comment on whether or not the proposed changes to the roadmap are something the community is willing to commit to.
Milestones should have target dates assigned to them to provide the community with a rough goal as to when each milestone should be completed. Tasks in the roadmap should have community members assigned to them to state who is responsible for the task itself, as well as a target milestone for completion. Although a task has a target milestone, tasks could be moved to later milestones by the community if so desired. The likely reason this could occur is the target milestone is nearing it’s completion date, but the the task itself is not complete.
Anyone can submit a pull request to the project, however, most pull requests should originate from one of two places:
- Issue Tracker Ticket
- Request for Comments (RFC)
Although the above are not a requirement, it’s less likely the community will accept a change to the project without the proper documentation, and socialization of the proposed change.
All pull requests must satisfy the requirements defined in the governance documentation. If the pull request includes source code, tests for the source code must also be included (usually in the form of unit tests). All CI tests must also return without error, demonstrating that not only does the source code contain the proper tests to validate it’s implementation, but these tests succeed.