diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..d18890bef --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,78 @@ +# Content Guidelines + +The issue tracker is exclusively for filing and discussing bugs, feature +requests, and tracking work items. It is not for technical support or general +discussion. Avoid discussing any illegal activity, such as downloading games. + +**Repeated misuses will result in a permanent project ban.** + +## Information Sourcing + +All information in xenia has been derived from reverse engineering legally-owned +games, hardware, and tools made public by Microsoft (such as the XNA Game Studio +tooling), scouring documentation made public by Microsoft (such as slide decks +and other presentations at conferences), and information from code made public +by 3rd party companies (like the Valve SDKs). + +The official Microsoft Xbox Development Kits (XDKs) are not to be used for any +information added to the project. The contributors do not want the XDKs, nor do +they want any information derived from them. The challenge of the project is +what makes it fun! Poisoning the codebase with code obtained by shady means +could result in the project being terminated, so just don't do it. + +**Posting any information directly from an XDK will result in a project ban.** + +# Contributing Code + +## Style Guide + +Please read over [style_guide.md](style_guide.md) before sending pull requests +and ensure your code is clean as the buildbot (or I) will make you to fix it :) +[style_guide.md](style_guide.md) has information about using `xb format` and +various IDE auto formatting tools so that you can avoid having to clean things +up later, so be sure to check it out. + +Basically: run `xb format` before you add a commit and you won't have a problem. + +## Clean Git History + +Tools such as `git bisect` are used on the repository regularly to check for and +identify regressions. Such tools require a clean git history to function +properly. Incoming pull requests must follow good git rules, the most basic of +which is that individual commits add functionality in somewhat working form and +fully compile and run on their own. Small pull requests with a single commit are +best, however multiple commits in a pull request are allowed only if they are +kept clean. If not, you will be asked to rebase them (and if you don't know what +that means, avoid getting into that situation ;). + +Example of a bad commit history: + +* Adding audio callback, random file loading, networking, etc. (+2000 lines) +* Whoops. +* Fixing build break. +* Fixing lint errors. +* Adding audio callback, second attempt. +* ... + +Histories like this make it extremely difficult to check out any individual +commit and know that the repository is in a good state. Rebasing, +cherry-picking, or splitting your commits into separate branches will help keep +things clean and easy. + +# License + +All xenia code is licensed under the 3-clause BSD license as detailed in +[LICENSE](LICENSE). Code under `third_party/` is licensed under its original +license. + +Incoming code in pull requests are subject to the xenia [LICENSE](LICENSE). +Once code comes into the codebase it is very difficult to ever fully remove so +copyright is ascribed to the project to prevent future disputes such as what +occurred in [Dolphin](https://dolphin-emu.org/blog/2015/05/25/relicensing-dolphin/). +That said: xenia will never be sold, never be made closed source, and never +change to a fundamentally incompatible license. + +Any `third_party/` code added will be reviewed for conformance with the license. +In general, GPL code is forbidden unless it is used exclusively for +development-time tooling (like compiling). LGPL code is strongly discouraged as +it complicates building. Unless extremely trivial (such as ) diff --git a/CONTRIBUTORS.md b/CONTRIBUTORS.md deleted file mode 100644 index 484b43905..000000000 --- a/CONTRIBUTORS.md +++ /dev/null @@ -1,7 +0,0 @@ -Contributors ------------- - -Names should be added to this file like so: `Name or Organization ` - -* Ben Vanik -* x1nixmzeng diff --git a/LICENSE b/LICENSE index d9d2dad5a..bc759869a 100644 --- a/LICENSE +++ b/LICENSE @@ -1,4 +1,4 @@ -Copyright (c) 2013, Ben Vanik. +Copyright (c) 2015, Ben Vanik. All rights reserved. Redistribution and use in source and binary forms, with or without diff --git a/README.md b/README.md index 874d57b96..26611bd3a 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,8 @@ Please check the [frequently asked questions](http://xenia.jp/faq/) page before asking questions. We've got jobs/lives/etc, so don't expect instant answers. Discussing illegal activities will get you banned. No warnings. +**Before contributing code or issues be sure to read [CONTRIBUTING.md](CONTRIBUTING.md).** + ## Status Buildbot: @@ -25,7 +27,9 @@ Project tracker: [![Stories in Ready](https://badge.waffle.io/benvanik/xenia.svg?label=ready&title=Ready)](http://waffle.io/benvanik/xenia) [![Stories in In Progress](https://badge.waffle.io/benvanik/xenia.svg?label=in%20progress&title=In%20Progress)](http://waffle.io/benvanik/xenia) -Some real games run. Most don't. Don't ask if GTA or whatever runs. [Game compatibility list](https://github.com/xenia-project/game-compatibility/issues). +Some real games run. Most don't. Don't ask if GTA or whatever runs. +See the [Game compatibility list](https://github.com/xenia-project/game-compatibility/issues) +for currently tracked games. ## Disclaimer @@ -42,20 +46,29 @@ Windows 8.1+ with Python 2.7 and [Visual Studio 2015](https://www.visualstudio.c > git clone https://github.com/benvanik/xenia.git > cd xenia > xb setup + + # Pull latest changes, rebase, and update submodules and premake: + > xb pull + # Build on command line: > xb build + # Run premake and open Visual Studio (run the 'xenia-app' project): > xb devenv + # Run premake to update the sln/vcproj's: > xb premake + # Format code to the style guide: + > xb format + When fetching updates use `xb pull` to automatically fetch everything and run premake for project files/etc. ## Building -See [building](docs/building.md) for setup and information about the -`xb` script. When writing code, check the [style guide](docs/style_guide.md) +See [building.md](building.md) for setup and information about the +`xb` script. When writing code, check the [style guide](style_guide.md) and be sure to run clang-format! ## Contributors Wanted! @@ -69,6 +82,7 @@ that there are some major work areas still untouched: * Help work through missing functionality/bugs in game [compat](https://github.com/benvanik/xenia/issues?labels=compat) * Add input drivers for [PS4 controllers](https://github.com/benvanik/xenia/issues/60) (or anything else) +* Skilled with Linux? A strong contributor is needed to [help with porting](https://github.com/benvanik/xenia/labels/cross%20platform) See more projects [good for contributors](https://github.com/benvanik/xenia/issues?labels=good+for+contributors&page=1&state=open). It's a good idea to ask on IRC/the bugs before beginning work on something. diff --git a/docs/building.md b/building.md similarity index 100% rename from docs/building.md rename to building.md diff --git a/docs/cpu.md b/docs/cpu.md index 3ba0d707e..a03deeade 100644 --- a/docs/cpu.md +++ b/docs/cpu.md @@ -1,9 +1,5 @@ # CPU Documentation -## Alloy - -TODO - ## Memory Management TODO diff --git a/docs/cpu_todo.md b/docs/cpu_todo.md index 7b1050452..c22c95903 100644 --- a/docs/cpu_todo.md +++ b/docs/cpu_todo.md @@ -16,15 +16,6 @@ will relocate the x64 when placing it in memory, which will be at a different location each time. Instead it would be nice to have the xbyak `calcJmpAddress` that performs the relocations use the address of our choosing. -### Stack Walking - -Currently the Windows/VC++ dbghelp stack walking is relied on, however this is -not portable, is slow, and cannot resolve JIT'ed symbols properly. Having our -own stack walking code that could fall back to dbghelp (via some pluggable -system) for host symbols would let us quickly get stacks through host and guest -code and make things like sampling profilers, kernel callstack tracing, and -other features possible. - ### Sampling Profiler Once we have stack walking it'd be nice to take something like diff --git a/docs/debugger.md b/docs/debugger.md deleted file mode 100644 index dc1a29802..000000000 --- a/docs/debugger.md +++ /dev/null @@ -1,37 +0,0 @@ -# Debugger - -## Protocol - -Framed messages: - -``` -[4b type] (0=request, 1=notification, etc) -[4b content source id] -[4b request/response id] -[4b size] -[payload] -``` - -## Content Sources - -### `xe::dbg::sources::MemorySource` - -[ ] Paged view into memory -[ ] Search operations -[ ] Live streaming updates -[ ] Writes - -### `xe::dbg::sources::ProcessorSource` - -[ ] Thread list -[ ] State read/write (per thread) -[ ] Modules -[ ] Statistics -[ ] Basic control (pause/resume) -[ ] Breakpoints/checkpoints/traces -[ ] Trace stream - -### `xe::dbg::sources::ModuleSource` - -[ ] Paged view into all symbols -[ ] Get function contents (data, disasm, llvm, x86, etc) diff --git a/src/xenia/hid/winkey/premake5.lua b/src/xenia/hid/winkey/premake5.lua index c2ecc8c5a..b30122d2a 100644 --- a/src/xenia/hid/winkey/premake5.lua +++ b/src/xenia/hid/winkey/premake5.lua @@ -13,6 +13,6 @@ project("xenia-hid-winkey") defines({ }) includedirs({ - project_root.."/third_party/elemental-forms/src", + project_root.."/third_party/elemental-forms/src", }) local_platform_files() diff --git a/docs/style_guide.md b/style_guide.md similarity index 67% rename from docs/style_guide.md rename to style_guide.md index 3da2c4b67..c1789af5d 100644 --- a/docs/style_guide.md +++ b/style_guide.md @@ -2,7 +2,8 @@ The style guide can be summed up as 'clang-format with the Google style set'. In addition, the [Google Style Guide](http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml) -is followed and cpplint is the source of truth. +is followed and cpplint is the source of truth. When in doubt, defer to what +code in the project already does. Base rules: @@ -10,18 +11,38 @@ Base rules: * LF (Unix-style) line endings * 2-space soft tabs, no TABs! * [Google Style Guide](http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml) for naming/casing/etc +* Sort includes according to the [style guide rules](http://google-styleguide.googlecode.com/svn/trunk/cppguide.html#Names_and_Order_of_Includes) +* Comments are properly punctuated (that means capitalization and periods, etc) +* TODO's must be attributed like `// TODO(yourgithubname): foo.` Code that really breaks from the formatting rules will not be accepted, as then no one else can use clang-format on the code without also touching all your lines. +### Why? + +To quote the [Google Style Guide](http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml): + +``` +One way in which we keep the code base manageable is by enforcing consistency. +It is very important that any programmer be able to look at another's code and +quickly understand it. Maintaining a uniform style and following conventions +means that we can more easily use "pattern-matching" to infer what various +symbols are and what invariants are true about them. Creating common, required +idioms and patterns makes code much easier to understand. In some cases there +might be good arguments for changing certain style rules, but we nonetheless +keep things as they are in order to preserve consistency. +``` + +## Buildbot Verification + The buildbot runs `xb lint --all` on the master branch, and will run `xb lint --origin` on pull requests. Run `xb format` before you commit each local change so that you are consistently clean, otherwise you may have to rebase. If you forget, run `xb format --origin` and rebase your changes (so you don't end up with 5 changes and then a 6th 'whoops' one - that's nasty). -The buildbot is running LLVM 3.6.1. If you are noticing style differences +The buildbot is running LLVM 3.8.0. If you are noticing style differences between your local lint/format and the buildbot, ensure you are running that version.