MyFavMirrors
/
moonfire-nvr
mirror of https://github.com/scottlamb/moonfire-nvr.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

add a contributing guide 

Questions about how to contribute come up from time to time, eg:
https://github.com/scottlamb/moonfire-nvr/issues/84#issuecomment-656065208
https://github.com/scottlamb/moonfire-nvr/issues/68#issuecomment-688938108

I hope this helps answer them. I think github adds a couple links to
a file called CONTRIBUTING or CONTRIBUTING.md so this filename gives it
some extra visibility.
This commit is contained in:
Scott Lamb 2021-04-01 15:20:39 -07:00
parent 4d4d78ba64
commit 770e76d342
4 changed files with 148 additions and 42 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.github/ISSUE_TEMPLATE/bug_report.md vendored
View File

@ -22,7 +22,7 @@ A clear and concise description of what you expected to happen.
**Server (please complete the following information):**
- If using Docker: `docker ps` + `docker images`
- If building from git: `git describe` + `moonfire-nvr --version`
- If building from git: `git describe --dirty` + `moonfire-nvr --version`
- Attach a [log file](https://github.com/scottlamb/moonfire-nvr/blob/master/guide/troubleshooting.md#viewing-moonfire-nvrs-logs). Run with the `RUST_BACKTRACE=1` environment variable set if possible.
**Screenshots**

114
CONTRIBUTING.md Normal file
View File

@ -0,0 +1,114 @@
# Contributing to Moonfire NVR <!-- omit in toc -->
Hi, I'm Scott, Moonfire NVR's author. I'd love your help in making it great.
There are lots of ways you can contribute.
* [Saying hi](#saying-hi)
* [Asking for support](#asking-for-support)
* [Offering support](#offering-support)
* [Filing bug and enhancement issues](#filing-bug-and-enhancement-issues)
* [Contributing documentation](#contributing-documentation)
* [Contributing code and UI changes](#contributing-code-and-ui-changes)
## Saying hi
Please say hi on the [mailing
list](https://groups.google.com/g/moonfire-nvr-users) or in [github
discussions](https://github.com/scottlamb/moonfire-nvr/discussions) after
trying out Moonfire NVR. Often open source authors only hear from users when
something goes wrong. I love to hear when it works well, too. It's motivating
to know Moonfire NVR is helping people. And knowing how people want to use
Moonfire NVR will guide development.
Great example: [this Show & Tell from JasonKleban](https://github.com/scottlamb/moonfire-nvr/discussions/118).
## Asking for support
When you're stuck, look at the [troubleshooting
guide](guide/troubleshooting.md). If it doesn't answer your question, please
ask for help! Support requests are welcome on the
[mailing list](https://groups.google.com/g/moonfire-nvr-users) or in [github
discussions](https://github.com/scottlamb/moonfire-nvr/discussions). Often
these discussions help create good bug reports and enhancement requests.
## Offering support
Answering someone else's question is a great way to help them and to test your
own understanding. You can also turn their support request into a bug report
or enhancement request.
## Filing bug and enhancement issues
First skim the [github issue
tracker](https://github.com/scottlamb/moonfire-nvr/issues) to see if someone
has already reported your problem. If so, no need to file a new issue. Instead:
* +1 the first comment so we know how many people are affected.
* subscribe so you know what's happening.
* add a comment if you can help understand the problem.
If there's no existing issue, file a new one:
* bugs: follow the [template](https://github.com/scottlamb/moonfire-nvr/issues/new?assignees=&labels=bug&template=bug_report.md&title=).
* enhancement requests: there's no template. Use your best judgement.
Please be understanding if your issue isn't marked as top priority. I have
many things I want to improve and only so much time. If you think something
is more important than I do, you might be able to convince me, but the most
effective approach is to send a PR.
## Contributing documentation
Moonfire NVR has checked-in documentation (in [guide](guide/) and
[design](design/) directories) to describe a particular version of Moonfire
NVR. Please send a github PR for changes. I will review them for accuracy
and clarity.
There's also a [wiki](https://github.com/scottlamb/moonfire-nvr/wiki). This
is for anything else: notes on compatibility with a particular camera, how to
configure your Linux system and network for recording, hardware
recommendations, etc. This area is less formal. No review is necessary; just
make a change.
## Contributing code and UI changes
I love seeing code and user interface contributions.
* Small changes: just send a PR. In most cases just propose a change against
`master`.
* Large changes: let's discuss the design first. We can talk on the issue
tracker, via email, or over video chat.
"Small" or "large" is about how you'd feel if your change isn't merged.
Imagine you go through all the effort of making a change and sending a PR,
then I suggest an alternate approach or point out your PR conflicts with some
other work on a development branch. You have to start over.
* if you'd be **frustrated** or **angry**, your change is **large**. Let's
agree on a design first so you know you'll be successful before putting
in this much work. When you're ready, open a PR. We'll polish and merge
it quickly.
* if you'd be **happy** to revise, your change is **small**. Send a PR
right away. I'd love to see your prototype and help you turn it into
finished software.
The [Building Moonfire NVR](guide/build.md) and [Working on UI
development](guide/developing-ui.md) guides should help you get started.
The [design documents](design/) will help you fit your work into the whole.
Please tell me when you get stuck! Every software developer knows in theory
there's parts of their code that aren't as clear and well-documented as they
should be. It's a whole other thing to know an unclear spot is actually
stopping someone from understanding and contributing. When that happens, I'm
happy to explain, expand design docs, write more comments, and revise code
for clarity.
I promise to review PRs promptly, even if it's for an issue I wouldn't
prioritize on my own. Together we can do more.
If you're looking for something to do:
* Please skim issues with the [`1.0` or `1.0?`
milestone](https://github.com/scottlamb/moonfire-nvr/issues?q=is%3Aopen+is%3Aissue+milestone%3A1.0+milestone%3A1.0%3F+). Let's ship a minimum viable product!
* Please help with UI and video analytics. These aren't my field of expertise.
Maybe you can teach me.

72
README.md
View File

@ -1,5 +1,8 @@
[![CI](https://github.com/scottlamb/moonfire-nvr/workflows/CI/badge.svg)](https://github.com/scottlamb/moonfire-nvr/actions?query=workflow%3ACI)
* [Introduction](#introduction)
* [Documentation](#documentation)
# Introduction
Moonfire NVR is an open-source security camera network video recorder, started
@ -12,6 +15,9 @@ analyze, or re-encode video frames, so it requires little CPU. It handles six
2](https://www.raspberrypi.org/products/raspberry-pi-2-model-b/), using
less than 10% of the machine's total CPU.
**Help wanted to make it great! Please see the [contributing
guide](CONTRIBUTING.md).**
So far, the web interface is basic: a filterable list of video segments,
with support for trimming them to arbitrary time ranges. No scrub bar yet.
There's also an experimental live view UI.
@ -25,7 +31,7 @@ There's also an experimental live view UI.
</tbody>
</table>
There's no support yet for motion detection, no https/SSL/TLS support (you'll
There's no support yet for motion detection, no https/TLS support (you'll
need a proxy server, as described [here](guide/secure.md)), and only a
console-based (rather than web-based) configuration UI.
@ -34,50 +40,36 @@ compatibility guarantees: configuration and storage formats may change from
version to version. There is an [upgrade procedure](guide/schema.md) but it is
not for the faint of heart.
I hope to add features such as salient motion detection. It's way too early to
make promises, but it seems possible to build a full-featured
hobbyist-oriented multi-camera NVR that requires nothing but a cheap machine
with a big hard drive. I welcome help; see [Getting help and getting
involved](#help) below. There are many exciting techniques we could use to
make this possible:
I hope to add features such as video analytics. In time, we can build
a full-featured hobbyist-oriented multi-camera NVR that requires nothing but
a cheap machine with a big hard drive. There are many exciting techniques we
could use to make this possible:
* avoiding CPU-intensive H.264 encoding in favor of simply continuing to use the
camera's already-encoded video streams. Cheap IP cameras these days provide
pre-encoded H.264 streams in both "main" (full-sized) and "sub" (lower
resolution, compression quality, and/or frame rate) varieties. The "sub"
stream is more suitable for fast computer vision work as well as
remote/mobile streaming. Disk space these days is quite cheap (with 4 TB
drives costing about $100), so we can afford to keep many camera-months of
both streams on disk.
* off-loading on-NVR analytics to an inexpensive USB or M.2 neural network
accelerator.
* taking advantage of on-camera analytics. This is the lowest CPU usage option,
although many cameras' analytics aren't as good as what can be done on the NVR,
they're hard to experiment with, and even when they use modern ML-based
approaches, their built-in models can't be retrained.
* avoiding CPU-intensive H.264 encoding in favor of simply continuing to use
the camera's already-encoded video streams. Cheap IP cameras these days
provide pre-encoded H.264 streams in both "main" (full-sized) and "sub"
(lower resolution, compression quality, and/or frame rate) varieties. The
"sub" stream is more suitable for fast computer vision work as well as
remote/mobile streaming. Disk space these days is quite cheap (with 4 TB
drives costing about $100), so we can afford to keep many camera-months
of both streams on disk.
* off-loading on-NVR analytics to an inexpensive USB or M.2 neural network
accelerator and hardware H.264 decoders.
* taking advantage of on-camera analytics. They're often not as accurate, but
they're the best way to stretch very inexpensive NVR machines.
# Documentation
* [Contributing](CONTRIBUTING.md)
* [License](LICENSE.txt) —
[GPL-3.0-or-later](https://spdx.org/licenses/GPL-3.0-or-later.html)
with [https://spdx.org/licenses/GPL-3.0-linking-exception.html](GPL-3.0-linking-exception)
for OpenSSL.
* [Installing](guide/install.md)
* [Building from source](guide/build.md)
* [UI Development](guide/developing-ui.md)
* [Troubleshooting](guide/troubleshooting.md)
* [Wiki](https://github.com/scottlamb/moonfire-nvr/wiki) has notes on
several camera models. Please add yours!
# <a name="help"></a> Getting help and getting involved
Please email the
[moonfire-nvr-users](https://groups.google.com/d/forum/moonfire-nvr-users)
mailing list with questions, or just to say you love/hate the software and
why. You can also file bugs and feature requests on the
[github issue tracker](https://github.com/scottlamb/moonfire-nvr/issues).
I'd welcome help with testing, development (in Rust, JavaScript, and HTML),
user interface/graphic design, and documentation. Please email the mailing
list if interested. Pull requests are welcome, but I encourage you to discuss
large changes on the mailing list or in a github issue first to save effort.
* [Guides](guide/)
* [Installing](guide/install.md)
* [Building from source](guide/build.md)
* [UI Development](guide/developing-ui.md)
* [Troubleshooting](guide/troubleshooting.md)
* [Design documents](design/)
* [Wiki](https://github.com/scottlamb/moonfire-nvr/wiki) has hardware
recommendations and notes on several camera models. Please add yours!

2
design/api.md
View File

@ -25,13 +25,13 @@ Status: **current**.
## Objective
Allow a JavaScript-based web interface to list cameras and view recordings.
Support external analytics.
In the future, this is likely to be expanded:
* configuration support
* commandline tool over a UNIX-domain socket
(at least for bootstrapping web authentication)
* mobile interface
## Detailed design