提交 41731bb0 编写于 作者: J jp9000

Improve README/CONTRIBUTING files

Use reStructuredText to allow HTML formatting while still maintaining
clarity in the raw text.
上级 b63e4b05
Contributing Information:
- Our bug tracker is located at (currently linked to forum accounts):
https://obsproject.com/mantis/
- Development forums are currently located at:
https://obsproject.com/forum/list/general-development.21/
- Development IRC channel is primarily #obs-dev on QuakeNet
- To contribute translations, see:
https://obsproject.com/forum/threads/how-to-contribute-translations-for-obs.16327/
Contributing Guidelines:
- Code and commits will be reviewed. Reviews will be blunt and honest, and
your change probably won't go through the first time, or may be outright
rejected. It may require many revisions before changes are finally
accepted.
- If you want to avoid doing a lot of work only to have it rejected, discuss
what you want to change it in the main channels/forums/mailing lists before
actually working on it. Open source requires thick skin. Please don't be
discouraged if your changes don't go through, learn from it and get better.
- Coding style is Linux-style KNF (kernel normal form). This means K&R, 80
columns max, preferable maximum function length of approximately 42 lines, 8
character width tabs, lower_case_names, etc. I chose this for the sake of
the project. Don't argue about it, just do it. It takes no time to do.
See https://www.kernel.org/doc/Documentation/CodingStyle for a general
guideline (though not necessarily a rulebook, for example we allow the use
of boolean return values instead of ints for failure).
NOTE: C++ is an exception to the lower_case_only rule, CamelCase is
encouraged (though not required) to distinguish it from C code. Just a
personal and subjective stylistic thing on my part.
- Commits are not just changes to code; they should also be treated as
annotation to code. For that reason, do not put unrelated changes in a
single commit. Separate out different changes in to different commits, and
make separate pull requests for unrelated changes. Commits should be
formatted with the 50/72 standard, and should be descriptive and concise.
See http://chris.beams.io/posts/git-commit/ for a summary of how to make
good commit messages.
- Core code is C only (unless there's an operating system specific thing that
absolutely requires another language).
- Modules and UI may use C, C++, or Objective-C (for apple), though please try
to use C unless an API you're using requires C++ or Objective-C (such as
windows COM classes, or apple Objective-C APIs).
- If you don't quite know what to work on and just want to help, the bug
tracker has a list of things that need to be worked on.
- Try to respect the wishes of the author(s)/maintainer(s). A good maintainer
will always listen, and will often ask others on the project for their
opinions, but don't expect things to be completely democratic.
- Do not use dependencies for the sake of convenience. There's enough
dependencies as it is. Use them only if you absolutely have to depend on
them.
Contributing
============
Quick Links for Contributing
----------------------------
- Compiling and building OBS Studio:
https://github.com/jp9000/obs-studio/wiki/Install-Instructions
- Our bug tracker (linked to forum accounts):
https://obsproject.com/mantis/
- Development IRC channel: #obs-dev on QuakeNet
- Development forum:
https://obsproject.com/forum/list/general-development.21/
- To contribute language translations, do not make pull requests.
Instead, use crowdin. Read here for more information:
https://obsproject.com/forum/threads/how-to-contribute-translations-for-obs.16327/
Coding Guidelines
-----------------
- OBS Studio uses kernel normal form (linux variant), for more
information, please read here:
https://www.kernel.org/doc/Documentation/CodingStyle
- Avoid trailing spaces. To view trailing spaces before making a
commit, use "git diff" on your changes. If colors are enabled for
git in the command prompt, it will show you any whitespace issues
marked with red.
- Tabs for indentation, spaces for alignment. Tabs are treated as 8
columns wide.
- 80 columns max
Commit Guidlines
----------------
- OBS Studio uses the 50/72 standard for commits. 50 characters max
for the title (excluding module prefix), an empty line, and then a
full description of the commit, wrapped to 72 columns max. See this
link for more information: http://chris.beams.io/posts/git-commit/
- Make sure commit titles are always in present tense, and are not
followed by punctuation.
- Prefix commit titles with the module name, followed by a colon and a
space (unless modifying a file in the base directory). When
modifying cmake modules, prefix with "cmake". So for example, if you
are modifying the obs-ffmpeg plugin::
obs-ffmpeg: Fix bug with audio output
Or for libobs::
libobs: Fix source not displaying
- If you still need examples, please view the commit history.
Headers
-------
There's no formal documentation as of yet, so it's recommended to read
the headers (which are heavily commented) to learn the API.
Here are the most important headers to check out::
libobs/obs.h Main header
libobs/obs-module.h Main header for plugin modules
libobs/obs-source.h Creating video/audio sources
libobs/obs-output.h Creating outputs
libobs/obs-encoder.h Implementing encoders
libobs/obs-service.h Implementing custom streaming services
libobs/graphics/graphics.h Graphics API
UI/obs-frontend-api/obs-frontend-api.h
Front-end API
If you would like to learn from example, examine the default plugins
(in the <plugins> subdirectory). All features of OBS Studio are
implemented as plugins.
What is OBS?
This project is a rewrite of what was formerly known as "Open Broadcaster
Software", software originally designed for recording and streaming live
video content, efficiently.
Bug Tracker: https://obsproject.com/mantis/
We are no longer using GitHub issues! Please use Mantis, and only report
bugs and major issues. Do NOT use mantis to ask questions or request
features, please keep that to the forums.
Forum accounts are now linked to Mantis Bug Tracker. To use the bug
tracker, simply log in to the forums and then go to the bug tracker link
above.
What's the goal of rewriting OBS?
- Make it multiplatform. Use multiplatform libraries/functions/classes where
possible to allow this. Multi-platform support was one of the primary
reasons for the rewrite. This also means using a UI toolkit will be
necessary for user interface. It also means allowing the use of OpenGL as
well as Direct3D.
- Separate the application from the core, allowing custom application of
the core if desired, and easier extending of the user interface.
- Simplify complex systems to not only make it easier to use, but easier to
maintain.
- Write a better core API, and design the entire system to be modular.
- Now that we have much more experience, improve the overall design of all
the subsystems/API, and minimize/eliminate design flaws. Make it so we can
do all the things we've had trouble with before, such as custom outputs,
multiple outputs at once, better handling of inputs, custom services.
- Make a better/cleaner code base, use better coding standards, use standard
libraries where possible (not just STL and C standard library, but also
things like ffmpeg as well), and improve maintainability of the project as a
whole.
- Implement a new API-independent shader/effect system allowing better and
easier shaders usage and customization without having to duplicate shader
code.
- Better device support. Again, I didn't know what I was getting into when
I originally started writing code for devices. It evolved into a totally
convoluted mess. I would have improved the existing device plugin code, but
it was just all so fundamentally bad and flawed that it would have been
detrimental to progression to continue working on it rather than rewrite it.
What was wrong with the original OBS?
The original OBS was rewritten not because it was bad, at least in terms of
optimization. Optimization and graphics are things I love. However, there
were some serious problems with the code and design that were deep and
fundamental, which prevented myself and other developers from being able to
improve/extend the application or add new features very easily.
First, the design flaws:
- The original OBS was completely and hopelessly hard-coded for windows,
and only windows. It was just totally impossible to use it on other
systems.
- All the sub-systems were written before I really knew what I was getting
into. When I started the project, I didn't really fully comprehend the
scope of what I would need or how to properly design the project. My
design and plans for the application were just to write something that
would "stream games and a webcam, with things like overlays and such."
This turned out fine for most casual gamers and streamers (and very
successful), but left anyone wanting to do anything more advanced left
massively wanting.
- Subsystems and core functionalities intermingled in such a way that it
was a nightmare to get proper custom functionality out of it. Things
like QSV had to be meshed in with the main encoding loop, and it just
made things a nightmare to deal with. Custom outputs were nigh
impossible.
- The API was poorly designed because most of it came after I originally
wrote the application, it was more of an afterthought, and plugin API
would routinely break for plugin developers due to changing C++
interfaces (one of the reasons the core is now C).
- API was intermeshed with the main executable. The OBSApi DLL was
nothing more than basically this mutant growth upon OBS.exe that allowed
plugin developers to barely write plugins, but all the important API
code was actually stored in the executable. Navigation was a total mess.
- The graphics subsystem, while not bad, was incomplete, and though far
easier to use than bare D3D, wasn't ideal, and was hard-coded for D3D
specifically.
- The devices and audio code was poor, I had no idea what I was getting into
when I started writing them in. I did not realize beforehand all the
device-specific quirks that each device/system could have. Some devices
had bad timing and quirks that I never anticipated while writing them.
I struggled with devices, and my original design for the audio subsystem
for example morphed over and over into an abomination that, though works,
is basically this giant duct-taped zombie monster.
- Shaders were difficult to customize because they had to be duplicated if
you wanted slightly different functionality that required more than just
changing shader constants.
- Orientation of sources was fixed, and required special code for each
source to do any custom modification of rotation/position/scale/etc.
This is one of those fundamental flaws that I look back on and regret, as
it was a stupid idea from the beginning. I originally thought I could
get more accurate source position/sizes, but it just turned out to be
totally bad. Should have been matrices from the beginning just like with
a regular 3D engine.
Second, the coding flaws:
- The coding style was inconsistent.
- C++98, C-Style C++, there was no exception usage, no STL. C++ used
poorly.
- Not Invented Here Syndrome everywhere. Custom string functions/classes,
custom templates, custom everything everywhere. To be fair, it was all
hand-me-down code from the early 2000s that I had become used to, but
that was no excuse -- C-standard libraries and the STL should have been
used from the beginning over anything else. That doesn't mean to say
that using custom stuff is always bad, but doing it to the extent I did
definitely was. Made it horrible to maintain as well, required extra
knowledge for plugin developers and anyone messing with the code.
- Giant monolithic classes everywhere, the main OBS class was paricularly
bad in this regard. This meant navigation was a nightmare, and no one
really knew where to go or where to add/change things.
- Giant monolithic functions everywhere. This was particularly bad
because it meant that functions became harder to debug and harder to
keep track of what was going on in any particular function at any given
time. These large functions, though not inefficient, were delicate and
easily breakable. (See OBS::MainCaptureLoop for a nightmarish example,
or the listbox subclass window procedure in WindowStuff.cpp)
- Very large file sizes with everything clumped up into single files (for
another particularly nightmarish example, see WindowStuff.cpp)
- Bad formatting. Code could go beyond 200 columns in some cases, making
it very unpleasant to read with many editors. Spaces instead of tabs,
K&R mixed with allman (which was admittedly my fault).
New (actual) coding guidelines
- For the C code (especially in the core), guidelines are pretty strict K&R,
kernel style. See the linux kernel "CodingStyle" document for more
information. That particular coding style guideline is for more than just
style, it actually helps produce a better overall code base.
- For C++ code, I still use CamelCase instead of all_lowercase just because
I prefer it that way, it feels right with C++ for some reason. It also
helps make it distinguishable from C code.
- I've started using 8-column tabs for almost everything -- I really
personally like it over 4-column tabs. I feel that 8-column tabs are very
helpful in preventing large amounts of indentation. A self-imposed
limitation, if you will. I also use actual tabs now, instead of spaces.
Also, I feel that the K&R style looks much better/cleaner when viewed with
8-column tabs.
- Preferred maximum columns: 80. I've also been doing this because in
combination with 8-column tabs, it further prevents large/bad functions
with high indentation. Another self-imposed limitation. Also, it makes
for much cleaner viewing in certain editors that wrap (like vim).
OBS Studio <https://obsproject.com>
===================================
What is OBS Studio?
-------------------
OBS Studio is software designed for capturing, compositing, encoding,
recording, and streaming video content, efficiently.
It's distributed under the GNU General Public License v2 - see the
accompanying COPYING file for more details.
Quick Links
-----------
- Website: https://obsproject.com
- Help/Guides: https://github.com/jp9000/obs-studio/wiki
- Forums: https://obsproject.com/forum/
- Build Instructions: https://github.com/jp9000/obs-studio/wiki/Install-Instructions
- Bug Tracker: https://obsproject.com/mantis/
(Note: The bug tracker is linked to forum accounts. To use the bug
tracker, log in to a forum account)
Contributing
------------
- If you wish to contribute code to the project, please make sure read
the coding and commit guidelines:
https://github.com/jp9000/obs-studio/blob/master/CONTRIBUTING.rst
- If you wish to contribute translations, do not submit pull requests.
Instead, please use Crowdin. For more information read this thread:
https://obsproject.com/forum/threads/how-to-contribute-translations-for-obs.16327/
- Other ways to contribute are by helping people out with support on
our forums or in our community chat. Please limit support to topics
you fully understand -- bad advice is worse than no advice. When it
comes to something that you don't fully know or understand, please
defer to the official help or official channels.
Markdown is supported
0% .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑!
想要评论请 注册