Difference between revisions of "OpusContributing"

From XiphWiki
Jump to navigation Jump to search
m
(→‎How to report bugs: trac issues have been migrated to gitlab.xiph.org)
 
(7 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
== Community ==
 
== Community ==
  
Development discussions and questions take place on the Xiph.Org Opus mailing list (opus@xiph.org). Discussion related to the IETF process happen on the IETF codec working group mailing list (codec@ietf.org).
+
Development discussions and questions take place on the Xiph.Org Opus mailing list ([mailto:opus@xiph.org opus@xiph.org]).
 +
 
 +
Discussions related to the IETF process happen on the IETF codec working group mailing list ([mailto:codec@ietf.org codec@ietf.org]).
  
 
For archives of recent discussions, try:
 
For archives of recent discussions, try:
Line 8: Line 10:
 
* IETF [https://www.ietf.org/mail-archive/web/codec/current/maillist.html codec mailing list archives]
 
* IETF [https://www.ietf.org/mail-archive/web/codec/current/maillist.html codec mailing list archives]
  
Informal development chat and support happens in #opus on irc.freenode.net. You can join the chat room through a web interface if you don't have an IRC client.
+
Informal development chat and support happens in #opus on irc.freenode.net. You can join the chat room through a '''[https://webchat.freenode.net/ web interface]''' if you don't have an IRC client.
  
== How to contribute ==
+
== How To Contribute ==
 +
 
 +
There are many ways to contribute to Opus development:
  
 
* Reporting and fixing bugs
 
* Reporting and fixing bugs
 
* Improving tools
 
* Improving tools
* Improving testing framework
+
* Improving testing framework - see the '''[https://github.com/xiph/opus/tree/master/tests test code]''' and the '''[[Opus_testvectors|Opus Test Vectors]]''' page
 
* Optimizations (assembly/intrinsics)
 
* Optimizations (assembly/intrinsics)
* Encoding quality improvements (listening/tuning)
+
* Encoding quality improvements - see the '''[[Opus tuning]]''' page for suggestions
* Mapping to new containers
+
* Mapping to new containers - see Opus within '''[[MatroskaOpus|Matroska]]''', '''[[Mp4Opus|MP4]]''', '''[[OpusTS|Mpeg-TS]]''' and '''[[OggOpus|Ogg]]''' containers (Ogg spec is on Standards Track as '''[https://tools.ietf.org/html/rfc7845 RFC 7845]''').
  
It is generally advisable to contact the developers on the mailing list or
+
It is generally advisable to contact the developers on the mailing list or the IRC channel before taking on new work on Opus,
IRC *before* taking on new work on Opus to avoid duplicating work and to
+
to avoid duplicating work and to make sure you're doing things the right way from the start.
make sure you're doing things the right way from the start.
 
  
 
== How to report bugs ==
 
== How to report bugs ==
  
You can report bugs in [https://trac.xiph.org/report/25 trac]. Please also notify developers on the mailing list.  
+
The '''[https://gitlab.xiph.org/ Xiph.Org GitLab]''' may be used to report bugs in [https://gitlab.xiph.org/xiph/opus/issues opus], [https://gitlab.xiph.org/xiph/opusfile/issues opusfile], [https://gitlab.xiph.org/xiph/libopusenc/issues libopusenc], or [https://gitlab.xiph.org/xiph/opus-tools/issues opus-tools]. Please also notify developers on the [mailto:opus@xiph.org mailing list].
  
For sensitive (security-related) bugs, please [https://www.opus-codec.org/contact/ contact] the developers
+
For sensitive (security-related) bugs, please '''[https://www.opus-codec.org/contact/ contact the developers]''' directly.
directly.
 
  
 
== How to submit a patch ==
 
== How to submit a patch ==
  
If you have a patch you would like to contribute, just send it to the mailing
+
If you have a patch you would like to contribute, just send it to the mailing list.
list. We can also take pull requests, but please send a note to the mailing
+
We can also take [https://github.com/xiph/opus/ Github] pull requests,
list since the github repository is only a mirror.
+
but please send a note to the mailing list since the GitHub Opus repository is only a mirror.
  
 
== Coding style ==
 
== Coding style ==
Line 41: Line 43:
 
have a consistent coding style. For example, the SILK code uses 4-space
 
have a consistent coding style. For example, the SILK code uses 4-space
 
indentation, while the rest of the code is mostly 3-space, except the entropy
 
indentation, while the rest of the code is mostly 3-space, except the entropy
coder, which is 2-space. The general rule is that you should follow the
+
coder, which is 2-space.
style of the code you're modifying. Do *not* reformat the code in your
+
 
patches, as it mostly makes it harder to review changes.  
+
The general rule is that you should follow the style of the code you're modifying.
 +
* '''Do not''' reformat the code in your "functional change" patches, as it mostly makes it harder to review changes.
 +
* '''Do''' send separate "format-fixing" patches, making sure they don't change Opus' functionality at all.
 +
 
 +
== Testing ==
 +
 
 +
For any new feature, it is strongly suggested to also include tests for the new code to make sure it works and keeps working in the future.
  
 
== Language ==
 
== Language ==
Line 53: Line 61:
 
To reduce the risk of exploitable memory errors, we do not use any function
 
To reduce the risk of exploitable memory errors, we do not use any function
 
pointers in the code unless they are declared as static const. We also
 
pointers in the code unless they are declared as static const. We also
have "flat" objects, which can be copied using a "shallow copy".
+
have "flat" objects, which can be copied using a "shallow copy", so do not add
 +
pointers to non-static data in the data structures.

Latest revision as of 20:41, 25 September 2018

Community

Development discussions and questions take place on the Xiph.Org Opus mailing list (opus@xiph.org).

Discussions related to the IETF process happen on the IETF codec working group mailing list (codec@ietf.org).

For archives of recent discussions, try:

Informal development chat and support happens in #opus on irc.freenode.net. You can join the chat room through a web interface if you don't have an IRC client.

How To Contribute

There are many ways to contribute to Opus development:

  • Reporting and fixing bugs
  • Improving tools
  • Improving testing framework - see the test code and the Opus Test Vectors page
  • Optimizations (assembly/intrinsics)
  • Encoding quality improvements - see the Opus tuning page for suggestions
  • Mapping to new containers - see Opus within Matroska, MP4, Mpeg-TS and Ogg containers (Ogg spec is on Standards Track as RFC 7845).

It is generally advisable to contact the developers on the mailing list or the IRC channel before taking on new work on Opus, to avoid duplicating work and to make sure you're doing things the right way from the start.

How to report bugs

The Xiph.Org GitLab may be used to report bugs in opus, opusfile, libopusenc, or opus-tools. Please also notify developers on the mailing list.

For sensitive (security-related) bugs, please contact the developers directly.

How to submit a patch

If you have a patch you would like to contribute, just send it to the mailing list. We can also take Github pull requests, but please send a note to the mailing list since the GitHub Opus repository is only a mirror.

Coding style

Opus is the result of merging three different codebases and therefore does not have a consistent coding style. For example, the SILK code uses 4-space indentation, while the rest of the code is mostly 3-space, except the entropy coder, which is 2-space.

The general rule is that you should follow the style of the code you're modifying.

  • Do not reformat the code in your "functional change" patches, as it mostly makes it harder to review changes.
  • Do send separate "format-fixing" patches, making sure they don't change Opus' functionality at all.

Testing

For any new feature, it is strongly suggested to also include tests for the new code to make sure it works and keeps working in the future.

Language

Opus only requires a C89 compiler, so any use of C99 and later constructs has to be optional (e.g. OPUS_INLINE). This is also why we do not use C++-style // comments.

To reduce the risk of exploitable memory errors, we do not use any function pointers in the code unless they are declared as static const. We also have "flat" objects, which can be copied using a "shallow copy", so do not add pointers to non-static data in the data structures.