From 8926e115cdafa360dfe216420ef4b8b008c08592 Mon Sep 17 00:00:00 2001 From: Ricardo Quesada Date: Thu, 6 Nov 2014 14:16:39 -0800 Subject: [PATCH] How to contribute to cocos2d-x --- docs/CONTRIBUTE.md | 197 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 197 insertions(+) create mode 100644 docs/CONTRIBUTE.md diff --git a/docs/CONTRIBUTE.md b/docs/CONTRIBUTE.md new file mode 100644 index 0000000000..6c4b8884ec --- /dev/null +++ b/docs/CONTRIBUTE.md @@ -0,0 +1,197 @@ +# Contributing to cocos2d-x + + +## For general questions + + +You can ask general questions by using: + +- Forum (preferred way): http://discuss.cocos2d-x.org/ +- IRC: https://webchat.freenode.net/ (Use the *cocos2d* or *cocos2d-x* channels) +- Weibo: http://t.sina.com.cn/cocos2dx +- Twitter: http://www.twitter.com/cocos2dx + +## Reporting bugs + +To report bugs, please use the [Issue Tracker](https://github.com/cocos2d/cocos2d-x/issues) + +Steps to report a bug: +* Open the [url](https://github.com/cocos2d/cocos2d-x/issues/new) +* Add all the needed information to reproduce the bug + + +## Submitting patches + +If you want to contribute code, please follow these steps: + +(If you are new to git and/or GitHub, you should read [Pro Git](http://progit.org/book/) , especially the section on [Contributing to a project:Small/Large Public Project](http://progit.org/book/ch5-2.html#public_small_project) ) + +- Download the latest cocos2d-x develop branch from github: + +``` +$ git clone git://github.com/cocos2d/cocos2d-x.git +$ cd cocos2d-x +$ git checkout v3 +$ ./download-deps.py +$ git submodule update --init +``` + +- Apply your changes in the recently downloaded repository +- Commit your changes in your own repository +- Create a new branch with your patch: `$ git checkout -b my_fix_branch` +- Push your new branch to your public repository +- Send a “pull request” to user “cocos2d” +- It must be _complete_. See the definition below +- It must follow the _Releases_ rules. See the definition below + +## Only _complete_ patches will be merged + +The patch must be _complete_. And by that, we mean: + +- Follow the [Cocos2d C++ Coding Style][1] +- Describe what the patch does +- Include test cases +- Include unit tests if applicable +- Must be tested in all supported platforms [*] +- Must NOT degrade the performance +- Must NOT break existing tests cases +- Must NOT break the Continuous Integration build +- Must NOT break backward compatibility +- Must compile WITHOUT warnings +- New APIs MUST be **easy to use**, **familiar** to cocos2d-x users +- Code MUST be **easy to extend** +- Must be efficient (fast / low memory needs) +- It must not duplicate existing code, unless the new code deprecates the old one +- Patches that refactor key components will only be merged in the next major versions. + +[*]: If you don't have access to test your code in all the supported platforms, let us know. + +## Releases Rules + +### Backward compatibility + +- Minor versions MUST be backward compatible with previous minor versions. eg: v3.2 must be backward compatible with v3.1 and v3.0. +- Major versions SHOULD be backward compatible with previous major versions. Breaking backward compatibility in Major versions is acceptable only if it is extremely well justified + +### Deprecated APIs + +- APIs introduced in a Major version MUST NOT be deprecated in the same Major version. eg: An API introduce in v3.1 MUST NOT be deprecated the following v3.x releases. +- Deprecated APIs can be removed only after being deprecated for more than one complete Major cycle. eg: An API deprecated in v2.2 can only be removed in v4.0, but not before. +- Deprecated APIs MUST give a compile-time warning. And MUST tell the user which is the new API that superceeds it. + +### Performance tests + +- Performance tests MUST be run before releasing a Release Candidate +- If performance is worse than previous version, then the Release Candidate MUST NOT be released (See Naming Conventions below) +- Results of the performance tests must be documented in the [spreadsheet](https://docs.google.com/spreadsheet/ccc?key=0AvvkdgVbWvpZdHFudzdDT3NuYTRNTHlZZzRGZWYzMmc#gid=8) + + +### Samples and tests + +**BEFORE** releasing a new Minor or Major stable release, the following tasks MUST be done: + +- All the samples and tests must be updated to use the new version. This includes: + - The samples in [cocos2d-x-samples](https://github.com/cocos2d/cocos2d-x-samples) repository + - The demo games [EarthWarrior3D](https://github.com/chukong/EarthWarrior3D) and [FantasyWarrior3D](https://github.com/chukong/FantasyWarrior3D) + - All the tests bundled in cocos2d-x + - All the templates bundled in cocos2d-x + +### Documentation + +**BEFORE** releasing a new Minor or Major stable release, the following tasks MUST be done: + +- All documentation MUST be updated to the new version. This includes: + - API Reference + - Programmers Guide + + +### Naming conventions + +#### Alpha + +The product is unstable. It could have memory leaks, or crashes, or the API is unstable. The product contains little QA. +Although the product is not ready for production, the product should be testable. +Alpha versions might have Core functionality that has just been refactored, meaning that Core functionality might be unstable, but should work Ok. + +As an example, for cocos2d-x, an _Alpha_ version means: + +* Basic functionality works Ok (not great, but OK), like Sprites, Scenes, actions, etc. +_* But it might have memory leaks, or crashes, or the recently added features might be unfinished. The documentation might not be updated. +* As an example, the Renderer refactoring must be done in "alpha" versions (but not Beta versions). + +Alpha versions are NOT feature freeze. New features might be added in future alpha and beta versions. + + +#### Beta + +The product is more stable than _Alpha_. The product might crash, but not frequently. No major changes were made in core components. +Smaller features could be refactored in _Beta_ versions, but the core functionality is stable. +The product has more QA. +The only difference between _Alpha_ and _Beta_, is that _Beta_ is more stable than _Alpha_. And that in _Beta_ versions no new major features will be added. + +As an example, for cocos2d-x it means: + +* All the Core features (Sprites, Menu, Labels, Director, Transitions) are stable. Bug fixes could have been added into the Core functionality, but no major refactoring were done in the Core. +* But perhaps new features like the new Particle Engine could be unfinished, or the Cocos Studio reader might crash. +* Some cocos2d-x users might want to use a beta version for real games. + +Beta versions are NOT feature freeze. __Small__ new features might be added in future _Beta_ versions. New __BIG__ features that might affect the Core functionality must only be added in _Alpha_ versions, and not in _Beta_ versions. + + +#### Release Candidate +Release candidate means that, unless major bugs are found, the product is ready for release. +The difference between _Release Candidate__ and _Final_ is that RC has less testing than the final version. + +Many cocos2d-x users might want to try and use the RC releases for production. + +RC versions ARE feature freeze. No new features, no matter how small they are, MUST be added in RC versions, because as the name implies, it is a _Release Candiate_. + + +#### Final + +It is the new stable version. + +### Number conventions + +major.minor [revision | status] + +#### Major +The major number is increased when there are significant jumps in functionality such as changing the framework which could cause incompatibility with interfacing systems + +#### Minor: +The minor number is incremented when only minor features or significant fixes have been added. + +#### Revision: +The revision number is incremented when minor bugs are fixed. + +#### Status: +The status could be: alphaN, betaN or rcN. + +'N' is a number, and the first MUST always be 0. + +#### Examples + +v2.0-alpha0: + - New major version of cocos2d-x. + - Unstable + +v2.1.3: + - Stable version of cocos2d-x. It is the same as v2.1 plus some bug fixes. + +v2.2-beta0: + - Similar to v2.1.3, but some new features were added, but are not stable yet. + +v2.2: + - Similar to v2.1.3, but some small features were added. The new features are stable. + + + +# Promoting cocos2d + +Help us promote cocos2d-x by using the cocos2d logo in your game, or by mentioning cocos2d in the credits. + +[Logo Resources of Cocos2d-x][2] + + +[1]: https://github.com/cocos2d/cocos2d-x/blob/v3/docs/CODING_STYLE.md +[2]: http://www.cocos2d-x.org/wiki/Logo_Resources_of_Cocos2d-x