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

This commit is contained in:
Ben Vanik 2015-08-28 14:16:38 -07:00
parent 45816d801b
commit a79ef87889
10 changed files with 120 additions and 64 deletions

78
CONTRIBUTING.md Normal file
View File

@ -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 File

@ -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 File

@ -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 File

@ -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.

View File

@ -1,9 +1,5 @@
# CPU Documentation
## Alloy
TODO
## Memory Management
TODO

View File

@ -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 File

@ -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)

View File

@ -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.