1# Contribute 2 3**Opening a new issue?** Please read [ISSUES.md](../ISSUES.md) first. 4 5Contributing to Cataclysm: Dark Days Ahead is easy — simply fork the repository here on GitHub, make your changes, and then send us a pull request. 6 7Cataclysm:Dark Days Ahead is released under the Creative Commons Attribution ShareAlike 3.0 license. The code and content of the game is free to use, modify, and redistribute for any purpose whatsoever. See http://creativecommons.org/licenses/by-sa/3.0/ for details. 8This means any contribution you make to the project will also be covered by the same license, and this license is irrevocable. 9 10## Guidelines 11 12There are a couple of guidelines we suggest sticking to: 13 14* Add this repository as an `upstream` remote. 15* Keep your `master` branch clean. This means you can easily pull changes made to this repository into yours. 16* Create a new branch for each new feature or set of related bug fixes. 17* Never merge from your local branches into your `master` branch. Only update that by pulling from `upstream/master`. 18 19## Code Style 20 21Code style is enforced across the codebase by `astyle`. 22See [CODE_STYLE](../doc/CODE_STYLE.md) for details. 23 24## Translations 25 26The translation of Cataclysm: DDA is done using Transifex. 27Look at the [translation project](https://www.transifex.com/cataclysm-dda-translators/cataclysm-dda/) for an up-to-date list of supported languages. 28 29See [TRANSLATING](../doc/TRANSLATING.md) for more information: 30 31* [For translators](../doc/TRANSLATING.md#translators) 32* [For developers](../doc/TRANSLATING.md#developers) 33* [For maintainers](../doc/TRANSLATING.md#maintainers) 34 35## Doxygen Comments 36 37Extensive documentation of classes and class members will make the code more readable to new contributors. New doxygen comments for existing classes are a welcomed contribution. 38 39Use the following template for commenting classes: 40```c++ 41/** 42 * Brief description 43 * 44 * Lengthy description with many words. (optional) 45 */ 46class foo { 47``` 48 49Use the following template for commenting functions: 50```c++ 51/** 52 * Brief description 53 * 54 * Lengthy description with many words. (optional) 55 * @param param1 Description of param1 (optional) 56 * @return Description of return (optional) 57 */ 58int foo(int param1); 59``` 60 61Use the following template for commenting member variables: 62```c++ 63/** Brief description **/ 64int foo; 65``` 66 67Helpful pages: 68* [Doxygen Manual - Special Commands](https://www.doxygen.nl/manual/commands.html) 69* [Doxygen Manual - Standard Markdown](https://www.doxygen.nl/manual/markdown.html#markdown_std) 70* [Doxygen Manual - Frequently Asked Questions](https://www.doxygen.nl/manual/faq.html) 71 72### Guidelines for adding documentation 73* Doxygen comments should describe behavior towards the outside, not implementation, but since many classes in Cataclysm are intertwined, it's often necessary to describe implementation. 74* Describe things that aren't obvious to newcomers just from the name. 75* Don't describe redundantly: `/** Map **/; map* map;` is not a helpful comment. 76* When documenting X, describe how X interacts with other components, not just what X itself does. 77 78### Building the documentation for viewing it locally 79* Install doxygen 80* `doxygen doxygen_doc/doxygen_conf.txt ` 81* `firefox doxygen_doc/html/index.html` (replace firefox with your browser of choice) 82 83## Example Workflow 84 85#### Setup your environment 86 87*(This only needs to be done once.)* 88 891. Fork this repository here on GitHub. 90 912. Clone your fork locally. 92 93 $ git clone https://github.com/YOUR_USERNAME/Cataclysm-DDA.git 94 # Clones your fork of the repository into the current directory in terminal 95 963. Set commit message template. 97 98 $ git config --local commit.template .gitmessage 99 1004. Add this repository as a remote. 101 102 $ cd Cataclysm-DDA 103 # Changes the active directory in the prompt to the newly cloned "Cataclysm-DDA" directory 104 $ git remote add -f upstream https://github.com/CleverRaven/Cataclysm-DDA.git 105 # Assigns the original repository to a remote called "upstream" 106 107For further details about commit message guidelines please visit: 108- [codeinthehole.com](https://codeinthehole.com/tips/a-useful-template-for-commit-messages/) 109- [chris.beams.io](https://chris.beams.io/posts/git-commit/) 110- [help.github.com](https://help.github.com/articles/closing-issues-using-keywords/) 111 112#### Update your `master` branch 113 1141. Make sure you have your `master` branch checked out. 115 116 $ git checkout master 117 1182. Pull the changes from the `upstream/master` branch. 119 120 $ git pull --ff-only upstream master 121 # gets changes from "master" branch on the "upstream" remote 122 123 * Note: If this gives you an error, it means you have committed directly to your local `master` branch. [Click here for instructions on how to fix this issue](#why-does-git-pull---ff-only-result-in-an-error). 124 125 $ git push origin master 126 # optionally, push the synced master state to your fork 127 128#### Make your changes 129 1300. Update your `master` branch, if you haven't already. 131 1321. For each new feature or bug fix, create a new branch. 133 134 $ git branch new_feature 135 # Creates a new branch called "new_feature" 136 $ git checkout new_feature 137 # Makes "new_feature" the active branch 138 1392. Once you've committed some changes locally, you need to push them to your fork here on GitHub. 140 141 $ git push origin new_feature 142 # origin was automatically set to point to your fork when you cloned it 143 1443. Once you're finished working on your branch, and have committed and pushed all your changes, submit a pull request from your `new_feature` branch to this repository's `master` branch. 145 146 * Note: any new commits to the `new_feature` branch on GitHub will automatically be included in the pull request, so make sure to only commit related changes to the same branch. 147 148## Drafts 149If you file a PR but you're still working on it, please make it a [Draft](https://docs.github.com/en/free-pro-team@latest/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request-from-a-fork). 150 151![screenshot](https://docs.github.com/assets/images/help/pull_requests/pullrequest-send.png) 152 153This will tell the reviewers that you still intend to add more to the PR and we don't need to review it yet. When it's ready to be reviewed for a merger, just click the [`Ready for review`](https://docs.github.com/en/free-pro-team@latest/github/collaborating-with-issues-and-pull-requests/changing-the-stage-of-a-pull-request) button. 154 155![screenshot](https://docs.github.com/assets/images/help/pull_requests/ready-for-review-button.png) 156 157Please convert all your existing PRs with `[WIP]` in the title to Drafts. 158 159![screenshot](https://docs.github.com/assets/images/help/pull_requests/convert-to-draft-link.png) 160 161This can help speed up our review process by allowing us to only review the things that are ready for it, and will help prevent merging in anything that isn't completely ready. 162 163## Comment requests 164If you are also looking for suggestions then add a [CR] before the title text — "comments requested". Feel free to remove [CR] when you feel you got enough information to proceed. 165 166It is not required to solve or reference an open issue to file a PR, however, if you do so, you need to explain the problem your PR is solving in full detail. 167 168### All PRs should have a "Summary" section with one line 169Summary is a one-line description of your change that will be extracted and added to [the project changelog](../data/changelog.txt). 170 171The format is: 172``` 173#### Summary 174Category "description" 175``` 176 177The categories to choose from are: Features, Content, Interface, Mods, Balance, Bugfixes, Performance, Infrastructure, Build, I18N. 178 179Example: 180``` 181#### Summary 182Content "Adds new mutation category 'Mouse'" 183``` 184Or, if you want it treated as a minor tweak that doesn't appear in the changelog: 185``` 186#### Summary 187None 188``` 189 190See [the Changelog Guidelines](../doc/CHANGELOG_GUIDELINES.md) for explanations of the categories. 191 192### Closing issues using keywords 193 194One more thing: when marking your PR as closing, fixing, or resolving issues, please include "XXXX #???" somewhere in the description, where XXX is on this list: 195* close 196* closes 197* closed 198* fix 199* fixes 200* fixed 201* resolve 202* resolves 203* resolved 204 205The "???" is the issue number. This automatically closes the issue when the PR is pulled in, and allows merges to work slightly faster. To close multiple issues format it as "XXXX #???, XXXX#???". 206 207See https://help.github.com/articles/closing-issues-using-keywords/ for more. 208 209## Keep your PR description relevant 210 211Make sure your PR description is still relevant every time you change your branch after discussion or additional thought. 212 213## Tooling support 214 215Various tools are available to help you keep your contributions conforming to the appropriate style. See [the relevant docs](../doc/DEVELOPER_TOOLING.md) for more details. 216 217## Advanced Techniques 218 219These guidelines aren't essential, but they can make keeping things in order much easier. 220 221#### Using remote tracking branches 222 223Remote tracking branches allow you to easily stay in touch with this repository's `master` branch, as they automatically know which remote branch to get changes from. 224 225 $ git branch -vv 226 * master xxxx [origin/master] .... 227 new_feature xxxx .... 228 229Here you can see we have two branches; `master` which is tracking `origin/master`, and `new_feature` which isn't tracking any branch. In practice, what this means is that git won't know where to get changes from. 230 231 $ git checkout new_feature 232 Switched to branch 'new_feature' 233 $ git pull 234 There is no tracking information for the current branch. 235 Please specify which branch you want to merge with. 236 237In order to easily pull changes from `upstream/master` into the `new_feature` branch, we can tell git which branch it should track. (You can even do this for your local master branch.) 238 239 $ git branch -u upstream/master new_feature 240 Branch new_feature set up to track remote branch master from upstream. 241 $ git pull 242 Updating xxxx..xxxx 243 .... 244 245You can also set the tracking information at the same time as creating the branch. 246 247 $ git branch new_feature_2 --track upstream/master 248 Branch new_feature_2 set up to track remote branch master from upstream. 249 250 * Note: Although this makes it easier to pull from `upstream/master`, it doesn't change anything with regards to pushing. `git push` fails because you don't have permission to push to `upstream/master`. 251 252 $ git push 253 error: The requested URL returned error: 403 while accessing https://github.com/CleverRaven/Cataclysm-DDA.git 254 fatal: HTTP request failed 255 $ git push origin 256 .... 257 To https://github.com/YOUR_USERNAME/Cataclysm-DDA.git 258 xxxx..xxxx new_feature -> new_feature 259 260## Unit tests 261 262There is a suite of tests built into the source tree at tests/ 263You should run the test suite after ANY change to the game source. 264An ordinary invocation of `make` will build the test executable at tests/cata_test, and it can be invoked like any ordinary executable, or via `make check`. 265Running `test/cata_test` with no arguments will run the entire test suite; running it with `--help` will print a number of invocation options you can use to adjust its operation. 266 267 $ make 268 ... compilation details ... 269 $ tests/cata_test 270 Starting the actual test at Fri Nov 9 04:37:03 2018 271 =============================================================================== 272 All tests passed (1324684 assertions in 94 test cases) 273 Ended test at Fri Nov 9 04:37:45 2018 274 The test took 41.772 seconds 275 276I recommend habitually invoking make like ``make YOUR BUILD OPTIONS && make check``. 277 278If you're working with Visual Studio (and don't have `make`), see [Visual Studio-specific advice](../doc/COMPILING/COMPILING-VS-VCPKG.md#running-unit-tests). 279 280If you want/need to add a test, see [TESTING.md](../doc/TESTING.md) 281 282## In-game testing, test environment and the debug menu 283 284Whether you are implementing a new feature or whether you are fixing a bug, it is always a good practice to test your changes in-game. It can be a hard task to create the exact conditions by playing a normal game to be able to test your changes, which is why there is a debug menu. There is no default key to bring up the menu so you will need to assign one first. 285 286Bring up the keybindings menu (press `Escape` then `1`), scroll down almost to the bottom and press `+` to add a new key binding. Press the letter that corresponds to the *Debug menu* item, then press the key you want to use to bring up the debug menu. To test your changes, create a new world with a new character. Once you are in that world, press the key you just assigned for the debug menu and you should see something like this: 287 288``` 289┌───────────────────────────────────────────────────────────────────────────┐ 290│ Debug Functions - Using these will cheat not only the game, but yourself. │ 291├───────────────────────────────────────────────────────────────────────────┤ 292│ i Info │ 293│ Q Quit to main menu │ 294│ s Spawning… │ 295│ p Player… │ 296│ t Teleport… │ 297│ m Map… │ 298└───────────────────────────────────────────────────────────────────────────┘ 299``` 300 301With these commands, you should be able to recreate the proper conditions to test your changes. You can find some more information about the debug menu on [the official wiki](http://cddawiki.chezzo.com/cdda_wiki/index.php). 302 303## Frequently Asked Questions 304 305#### Why does `git pull --ff-only` result in an error? 306 307If `git pull --ff-only` shows an error, it means that you've committed directly to your local `master` branch. To fix this, we create a new branch with these commits, find the point at which we diverged from `upstream/master`, and then reset `master` to that point. 308 309 $ git pull --ff-only upstream master 310 From https://github.com/CleverRaven/Cataclysm-DDA 311 * branch master -> FETCH_HEAD 312 fatal: Not possible to fast-forward, aborting. 313 $ git branch new_branch master # mark the current commit with a tmp branch 314 $ git merge-base master upstream/master 315 cc31d0... # the last commit before we committed directly to master 316 $ git reset --hard cc31d0.... 317 HEAD is now at cc31d0... ... 318 319Now that `master` has been cleaned up, we can easily pull from `upstream/master`, and then continue working on `new_branch`. 320 321 $ git pull --ff-only upstream master 322 # gets changes from the "upstream" remote for the matching branch, in this case "master" 323 $ git checkout new_branch 324 325For more frequently asked questions, see the [developer FAQ](../doc/DEVELOPER_FAQ.md). 326