mirror of
https://github.com/xenia-project/xenia.git
synced 2024-11-23 03:29:46 +00:00
Adding CONTRIBUTING.md so that github shows it on issues.
This commit is contained in:
Ben Vanik
parent
45816d801b
commit
a79ef87889
78
CONTRIBUTING.md
Normal file
78
CONTRIBUTING.md
Normal 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 )
|
||||
@ -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>
|
||||
2
LICENSE
2
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
|
||||
|
||||
20
README.md
20
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:
|
||||
[](http://waffle.io/benvanik/xenia)
|
||||
[](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.
|
||||
|
||||
@ -1,9 +1,5 @@
|
||||
# CPU Documentation
|
||||
|
||||
## Alloy
|
||||
|
||||
TODO
|
||||
|
||||
## Memory Management
|
||||
|
||||
TODO
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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,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.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user