Permalink
Browse files

Adding CONTRIBUTING.md so that github shows it on issues.

1 parent 45816d8 commit a79ef878893dbcdc0557ce784b55bdf7547ff0cb @benvanik committed Aug 28, 2015
Showing with 120 additions and 64 deletions.
  1. +78 −0 CONTRIBUTING.md
  2. +0 −7 CONTRIBUTORS.md
  3. +1 −1 LICENSE
  4. +17 −3 README.md
  5. 0 {docs → }/building.md
  6. +0 −4 docs/cpu.md
  7. +0 −9 docs/cpu_todo.md
  8. +0 −37 docs/debugger.md
  9. +1 −1 src/xenia/hid/winkey/premake5.lua
  10. +23 −2 {docs → }/style_guide.md
View
@@ -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 )
View
@@ -1,7 +0,0 @@
-Contributors
-------------
-
-Names should be added to this file like so: `Name or Organization <email address>`
-
-* Ben Vanik <ben.vanik@gmail.com>
-* x1nixmzeng <x1nixmzeng@live.co.uk>
View
@@ -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
View
@@ -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.
File renamed without changes.
View
@@ -1,9 +1,5 @@
# CPU Documentation
-## Alloy
-
-TODO
-
## Memory Management
TODO
View
@@ -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
View
@@ -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)
@@ -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()
@@ -2,26 +2,47 @@
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:
* 80 column line length max
* 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.

0 comments on commit a79ef87

Please sign in to comment.