Permalink
Browse files

Merge pull request #2232 from saagarjha/develop

Tweak prose to be more clear and inviting
  • Loading branch information...
saagarjha committed Jan 20, 2019
2 parents fbac25f + bda944c commit 3ff3674049dcd49af9c23a4e022d225c75abc97c
Showing with 92 additions and 110 deletions.
  1. +42 −46 CONTRIBUTING.md
  2. +50 −64 README.md
@@ -1,65 +1,61 @@
# Contributing

Thank you for being interested in IINA.
Thanks for your interest in contributing to IINA! IINA is not perfect, but it's our goal to make it the best it can be. Here's how you can help.

First of all, please be tolerant. I'm not a professional in Cocoa development or Swift, so my code, especially early parts may contain stupid logic or design flaws (a refactor is in my plans).
First of all, if you plan on doing any work, *please check the issue tracker*. Not only does this make it easier to track progress, it also prevents people doing duplicate work, as well as allows for the community to weigh in on the implementation of a feature *before* it's already all coded up. Nothing's more sad than having to go back and delete or rewrite code because of a misunderstanding in how it would fit into IINA :(

If you believe the code structures can be improved, please raise an issue.
## Contribution workflow

IINA follows the standard fork/commit/pull request process for integrating changes. If you have something that you're interested in working on (*after checking the issue tracker, of course ;)*):

1. Fork and clone the repository
2. Follow [the guide to build with pre-compiled dylibs in README.md](README.md#using-the-pre-compiled-libraries), unless you're modifying those.
3. Open `iina.xcworkspace` in Xcode. Again, make sure you are using the [latest public version of Xcode](https://itunes.apple.com/us/app/xcode/id497799835); IINA may build with another version but this is not guaranteed. Generally, around June, a new branch will pop up with support for the new version of macOS and associated developer tools; however, main development will still occur on `develop`.
4. Commit your changes, test them, push to your repository, and submit a pull request against iina/iina's `develop` branch.

Some tips for your pull request:

* If you found `develop` has been updated before your change was merged, you can rebase in the new changes before opening a pull request:

```console
$ git rebase upstream/develop
```
* Please submit separate pull requests for different features; i.e. try not to shove multiple, unrelated changes into one pull request.
* Please make sure the pull request only contains changes that you've made intentionally; if you didn't mean to touch a file, you should probably not include it in your commit. Here are some files that like to have spurious changes in them:
- `Podfile.lock`: This file may change if you have a different CocoaPods version installed than the project maintainers. We suggest updating to the ~~latest release~~ whatever `sudo gem install cocoapods --pre` gives you, at least until CocoaPods 1.6 is released.
- `project.pbxproj`: This file may change if you sign the project with a different developer account. Changes due to adding or removing files are OK, generally.
- `xib` files: Please discard changes to an `xib` file if you didn't change anything in it.

## Some Guidelines

- IINA is for modern macOS.
- Stay consistent with the design language of macOS.
- Stay consistent with behaviors of macOS original Applications.
- User interface and user experience is important.
* IINA is designed for modern versions of macOS.
- Stay consistent with the [macOS Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/macos/).
- Stay consistent with behaviors of the macOS built-in applications, except in certain exceptional cases.
* User interface and user experience is important.
- Use animations for UI items, if possible.
- Use proper font weight, size and color.
- Use the proper system font weight, size and color.
- Leave margins everywhere.
- IINA is based on mpv.
* IINA is based on mpv.
- Avoid adding features (especially decoding/playback related) that mpv does not provide.
- Lua scripts are also a possible solution for some features.
- Give users more choices.
* Give users more choices when possible.

**Technical tips**
### Technical tips

- Use a XIB for UI if possible for things like as positioning of UI elements, whether a view uses layer, Cocoa bindings, etc.
- Add proper comments.
- Use 2 spaces for indentation.
- There's no fixed guidelines for code style. Maybe later?
* Use a XIB for UI if possible for things like as positioning of UI elements, whether a view uses layer, Cocoa bindings, etc.
* Add comments when necessary.
* Use 2 spaces for indentation.
* There's no fixed guidelines for code style, unfortunately, so please use your best judgement in making the code look consistent. We may add one in the future.

**Current structure**
### Current structure

- Only `VideoView` and `MPVController` may call mpv APIs directly.
- `PlayerCore` encapsulates general playback functions.
* Only `VideoView` and `MPVController` may call mpv APIs directly.
* `PlayerCore` encapsulates general playback functions.
- Setting options/properties directly through `MPVController` is discouraged.
- `PlayerCore` should only contain logic that controls playback.
- Window related logic should be in `MainWindowController`.
* Window related logic should be in `MainWindowController`.
- `windowDidLoad()`: stuff that should be done once
- `windowDidOpen()`: stuff that should be done every time when window shown, like resetting some UI components. Note that window is not necessarily loaded here.
- `windowWillClose()`: release / deinitialize

## How to Contribute
- `windowDidOpen()`: stuff that should be done every time when window shown, like resetting some UI components. Note that the window may not necessarily loaded here.
- `windowWillClose()`: release resources and deinitialize

**Please open an issue and ask for permission from the author before actually starting doing something** to make sure that there's not someone else working on the same feature.

1. Fork and clone the repository
2. Follow [the guide to build with pre-compiled dylibs in README.md](README.md#use-pre-compiled-dylibs)
3. Open `iina.xcworkspace`.
4. Commit changes, test, push, and submit a pull request.

If you want to build libmpv and other depended dylibs on your own, please refer to [the guide in README.md](README.md#build-with-the-latest-mpv).

**Pull requests**

- Please set base branch of your pull request to `develop`.
- If you found `develop` has been updated during your change, remember to do a rebase before opening a pull request:

```
git rebase upstream/develop
```
- Please submit separate pull requests for different features.
- Please make sure the pull request only contains changes made by yourself *intentionally*. Here are some examples:
- `Podfile.lock`: This file may change if you have a different Cocoapods version installed. We suggest updating to the latest beta release by `sudo gem install cocoapods --pre`.
- `project.pbxproj`: This file may change if you sign the project with a different developer account.
- `xib` files: Please discard changes to an `xib` file if you didn't change anything in it.

If you believe the code can be improved, please raise an issue.
114 README.md
@@ -12,84 +12,70 @@
<a href="https://t.me/joinchat/AAAAAEBemW7dU8X7IHShwQ">Telegram Group</a>
</p>

***

# Features

- Based on [mpv](https://github.com/mpv-player/mpv), which provides the best decoding capacity on macOS
- Designed for modern macOS (10.11+), aims to offer the best user experience
- All the features you need for videos, audios, subtitles, playlist, chapters and so on
- Force Touch, Picture-in-picture and (advanced) Touch Bar support
- Customizable user interface including color schemes and on screen controller (OSC) layout
- Standalone Music Mode designed for audio files
- Thumbnail preview for the whole timeline like YouTube
- Online subtitle searching and intelligent local subtitle matching
- Unlimited playback history
- Convenient and interactive settings for video/audio filters
- Fully customizable keyboard, mouse and trackpad gesture control
- MPV config files and script system are available for advanced users
- Command Line Tool and browser extensions provided
- Still in active development

# Build

**Use pre-compiled dylibs**

1. Please make sure CocoaPods is installed.

**gem**
```
sudo gem install cocoapods
```
**homebrew**
```
brew install cocoapods
```

2. Run pod install in project root directory.
```
pod install
```

3. Open `.xcworkspace` file using Xcode 10.

There's a bug in cocoapods 1.5.*, so that you cannot compile IINA with it. Thankfully the bug was fixed in their master branch. We are using pre-release of cocoapods (currently 1.6.0 beta2) to avoid that bug. You can install the pre-release version of cocoapods via
```
sudo gem install cocoapods --pre
```
---

## Features

_If you are unwilling to use the provided dylibs, follow the instructions below._
* Based on [mpv](https://github.com/mpv-player/mpv), which provides the best decoding capacity on macOS
* Designed with modern versions of macOS (10.11+) in mind
* All the features you need for video and music: subtitles, playlists, chapters…and much, much more!
* Force Touch, picture-in-picture and advanced Touch Bar support
* Customizable user interface including multiple color schemes and on screen controller (OSC) layout positioning
* Standalone Music Mode designed for audio files
* Video thumbnails
* Online subtitle searching and intelligent local subtitle matching
* Unlimited playback history
* Convenient and interactive settings for video/audio filters
* Fully customizable keyboard, mouse, trackpad, and gesture controls
* mpv configuration files and script system for advanced users
* Command line tool and browser extensions provided
* In active development

**Build with the latest mpv**
## Building

* Install mpv
IINA ships with pre-compiled dynamic libraries for convenience reasons. If you aren't planning on modifying these libraries, you can follow the instructions below to build IINA; otherwise, skip down to [Building mpv manually](#building-mpv-manually) and then run the steps here:

```
brew install mpv --with-uchardet
```
### Using the pre-compiled libraries

Feel free to include any other libraries if you like.
1. IINA uses [CocoaPods](https://cocoapods.org) for managing the installation of third-party libraries. If you don't already have it installed, here's how you can do so:

* Copy latest [header files](https://github.com/mpv-player/mpv/tree/master/libmpv) into `libmpv/include/mpv/`
*Note: The current stable version of CocoaPods [has an unfortunate bug](https://github.com/CocoaPods/CocoaPods/issues/7708) that prevents IINA from building, which has luckily been fixed in their master branch and set to roll out in version 1.6. To get access to this version, please install CocoaPods with `sudo gem install cocoapods --pre` and ignore the installation instructions below*.

* other/parse_doc.rb
### Using RubyGems
```console
$ sudo gem install cocoapods
```

This script will fetch the *latest* mpv documentation and generate `MPVOption.swift`, `MPVCommand.swift` and `MPVProperty.swift`. This is only needed when updating libmpv. Note that if the API changes, the player source code may also need to be changed.
### Using Homebrew
```console
$ brew install cocoapods
```

* other/change_lib_dependencies.rb
2. Run `pod install` in project's root directory.

This script will deploy the depended libraries into `libmpv/libs`.
Make sure you have a phase copying of all these dylibs in Xcode's build settings.
3. Open iina.xcworkspace in the [latest public version of Xcode](https://itunes.apple.com/us/app/xcode/id497799835). *IINA may not build if you use any other version.*

## Contributing
## Building mpv manually

**Please read [CONTRIBUTING.md](https://github.com/lhc70000/iina/blob/master/CONTRIBUTING.md) before opening an issue or pull request.**
1. Install mpv:

**Please ask for permission from the author before starting working on a pull request** to make sure that there's not someone else working on the same feature.
```console
$ brew install mpv --with-uchardet
```
Feel free to include your own copies of the other libraries if you'd like.

2. Copy latest [header files](https://github.com/mpv-player/mpv/tree/master/libmpv) into `libmpv/include/mpv/`.

3. Run `other/parse_doc.rb`. This script will fetch the latest mpv documentation and generate `MPVOption.swift`, `MPVCommand.swift` and `MPVProperty.swift`. This is only needed when updating libmpv. Note that if the API changes, the player source code may also need to be changed.

4. Run `other/change_lib_dependencies.rb`. This script will deploy the depended libraries into `libmpv/libs`.
Make sure you have a phase copying of all these dylibs in Xcode's build settings.

## Contributing

Any feedback/contribution is appreciated!
IINA is always looking for contributions, whether it's through bug reports, code, or new translations.

**Translation**
* If you find a bug in IINA, or would like to suggest a new feature or enhancement, it'd be nice if you could [search your problem first](https://github.com/iina/iina/issues); while we don't mind duplicates, keeping issues unique helps us save time and considates effort. If you can't find your issue, feel free [to file a new one](https://github.com/iina/iina/issues/new).

Please check [Translation Status](https://github.com/iina/iina/wiki/Translation-Status) first. If a language is labeled as "Need help", then please feel free to [update](https://github.com/iina/iina/wiki/Translation#update-translations) the translation. If it doesn't contain your language, it will be awesome to [submit a new translation](https://github.com/iina/iina/wiki/Translation). Please contact the author ([@lhc70000](https://github.com/lhc70000)) if you don't know how to submit translations using GitHub.
* If you're looking to contribute code, please read [CONTRIBUTING.md](CONTRIBUTING.md)–it has information on IINA's process for handling contributions, and tips on how the code is structured to make your work easier.
* If you'd like to translate IINA to your language, please check the [Translation Status](https://github.com/iina/iina/wiki/Translation-Status) page first: if a language is labeled as "Need help", then feel free to [update the translation](https://github.com/iina/iina/wiki/Translation#update-translations). If it doesn't contain your language at all, you can [submit a new translation](https://github.com/iina/iina/wiki/Translation). If you need help working on a translation, you can contact [@lhc70000](https://github.com/lhc70000) or file an issue and one of the maintainers will try to help you out.

0 comments on commit 3ff3674

Please sign in to comment.