= NNG Contributing Guidelines
|
|
Legal stuff:
|
|
For any submission you make to us, either by filing an issue, or submitting a
|
defect, or sending us a message, you agree and certify that:
|
|
** You are the author or legal owner of the content submitted, or
|
you have authorization to submit the content by the owner
|
(such as your employer).
|
|
** Unless the submission is otherwise labeled, you or the owner
|
are granting the NNG Project, its contributors, and licensees,
|
a non-exclusive license to your use submission under the terms of
|
MIT License (as documented in the <<LICENSE#,LICENSE>> file in this
|
repository.) This grant shall include a right to use for any
|
patents covering content in the submission.
|
|
** You are not aware of any legal encumbrances to the use of the
|
submission (such as patents held by others) unless explicitly
|
stated otherwise.
|
|
** You have read, and agree to abide by, our
|
<<CODE_OF_CONDUCT#,Code of Conduct>>.
|
|
** You understand that participation in this project is voluntary,
|
and at no point shall any of the project members or leadership
|
be obligated to review, merge, or handle any submission.
|
|
== Filing Issues
|
|
We use github issues for NNG. We ask that you keep in mind the following
|
when filing issues:
|
|
* First look to see if your issue is already covered by an existing issue.
|
|
* Synopsis should be brief, but descriptive. (We may alter the synopsis
|
to correct its accuracy or improve its brevity.)
|
|
* Include details about the platform (operating system, language).
|
|
* Include CMake configuration used to build NNG.
|
|
* Include expected results or behavior, and observed results or behavior.
|
|
* If at all possible, a reproducible test case is helpful. We prefer test
|
cases as the minimal amount of C code to demonstrate the defect.
|
|
* Please file issues only when filing things that should be fixed by
|
changes to the source or documentation in the repository (such as bugs
|
or feature requests). For support questions and other discussion, please
|
instead use the mailing list
|
https://www.freelists.org/list/nanomsg
|
or Gitter chat
|
https://gitter.im/nanomsg/nanomsg .
|
|
== Pull Requests
|
|
* We use Github PRs
|
|
* Please follow the existing coding style.
|
|
** See the `.clang-format` for whitespace rules.
|
** Return values should be enclosed in parenthesis.
|
** Conditional clauses are always enclosed in braces, and thus
|
span multiple lines.
|
|
TIP: The `.clang-format` file and `clang-format` may be helpful, but
|
is not necessarily complete. Also you may need to use a recent version
|
of `clang-format` as older versions can differ in their output.
|
|
* If you submit a PR, we would appreciate it if you would respond to review
|
feedback, rather than just leaving your baby on our doorstep. Abandoned
|
PRs or issues may be closed without further action.
|
|
* Commits should have comments formatted like this:
|
|
----
|
fixes #<issue#1> <issue#1-synopsis>
|
fixes #<issue#2> <issue#2-synopsis>
|
|
<Comments describing the issues, or fix, that you want to have
|
in the commit history. Not every issue needs such comments.>
|
----
|
|
* We have an "always release ready" policy for our tree, meaning we should
|
be able to build a functional release at any commit boundary. This ensures
|
that others taking the work can use git bisect and similar approaches when
|
hunting down regressions, or when cherry-picking changes for their own
|
forked copies. This has a few consequences:
|
|
** PRs should be functionally complete (that is, don't submit a
|
PR with partial work in progress, unless you have reached a
|
milestone that can stand on its own merit.)
|
|
** Each commit in a PR should also be "complete", so that
|
a release could be cut in between your commits without
|
leaving the tree in a broken or dysfunctional state.
|
|
** Usually this means its best to address only one issue in a PR,
|
with just one commit (squashed).
|
|
** Please have already merged and tested your code against the
|
latest changes in master. (If your code has merge conflicts,
|
your PR will be rejected until you have fixed the conflicts.)
|
|
* As a special exception, you may submit a PR for handling by our test
|
infrastructure; in that case please clearly identify that the PR is
|
submitted for that purpose, and should not considered for integration
|
yet. When that testing is done, please close the PR, and submit a new
|
one when you are ready for final review and integration.
|
|
* Code submitted should contain updates to any copyright files to add
|
your copyright to the license. We prefer you follow the existing
|
style of copyright, `// Copyright <year> <owner> <email or url>`
|
|
NOTE: We only use the most recent year, and we do not use `\(C)` which has
|
no legal value when the word "`Copyright`" is already present. We also
|
do not use the old "`All rights reserved.`" statement, which is equally
|
meaningless under current international copyright law.
|
|
* When updating an existing file, any new Copyright notice should be
|
added immediately below the pre-existing one, just before the license
|
boilerplate.
|
|
* All new files should use the MIT license and the same boilerplate
|
from one of the other files. We do not normally approve submissions
|
with different license or boilerplates -- please contact us if you
|
have a compelling reason for wanting to do that.
|
