| title |
|---|
Contributing |
:::tip{title="Opening new issue"}
Check how to open a issue.
:::
Help is appreciated, especially with:
- Reporting bugs. Including ones inherited from DDA.
- Identifying problems that aren't bugs. Misleading descriptions, values that are clearly off compared to similar cases, grammar mistakes, UI wonkiness that has an obvious solution.
- Making useless things useful or putting them on a blacklist. Adding deconstruction recipes for things that should have them but don't, replacing completely redundant items with their generic versions (say, "tiny marked bottle" with just "tiny bottle") in spawn lists.
- Tileset work. I'm occasionally adding new objects, like the new electric grid elements, and they could use new tiles.
- Balance analysis. Those should be rather in depth or "obviously correct". Obviously correct would be things like: "weapon x has strictly better stats than y, but y requires rarer components and has otherwise identical requirements".
- Identifying performance bottlenecks with a profiler.
- Code quality help.
Contributing to Cataclysm: Bright Nights is easy:
- Fork the repository here on GitHub.
- Make your changes.
- Send us a pull request.
:::note{title="License"}
Cataclysm: Bright Nights 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. This means any contribution you make to the project will also be covered by the same license, and this license is irrevocable.
:::
There are a couple of guidelines we suggest sticking to:
- Add this repository as an
upstreamremote. - Keep your
mainbranch clean. This means you can easily pull changes made to this repository into yours. - Create a new branch for each new feature or set of related bug fixes.
- Never merge from your local branches into your
mainbranch. Only update that by pulling fromupstream/main.
Code style is enforced across the codebase by astyle. See
CODE_STYLE for details.
JSON files are formatted using custom formatter available in tools/format. Visit
JSON Style Guide for details.
Markdown files such as doc/ are formatted using deno's built-in formatter.
Run deno fmt anywhere to format markdown files. On
VSCode, you can set following configuration to auto-format markdown files on save:
// .vscode/settings.json
{
"[markdown]": {
"editor.formatOnSave": true,
"editor.defaultFormatter": "denoland.vscode-deno"
}
}Lua files are formatted using dprint's built-in formatter. Run
deno task dprint fmt anywhere to format Lua files. For details,
see Lua Style Guide.
The translation of Cataclysm: BN is done using Transifex. Look at the translation project for an up-to-date list of supported languages.
For more information:
Extensive 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.
Use the following template for commenting classes:
/**
* Brief description
*
* Lengthy description with many words. (optional)
*/
class foo {
}Use the following template for commenting functions:
/**
* Brief description
*
* Lengthy description with many words. (optional)
* @param param1 Description of param1 (optional)
* @return Description of return (optional)
*/
int foo(int param1);Use the following template for commenting member variables:
/** Brief description **/
int foo;- 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.
- Describe things that aren't obvious to newcomers just from the name.
- Don't describe redundantly:
/** Map **/; map* map;is not a helpful comment. - When documenting X, describe how X interacts with other components, not just what X itself does.
- Install doxygen
doxygen doxygen_doc/doxygen_conf.txtfirefox doxygen_doc/html/index.html(replace firefox with your browser of choice)
(This only needs to be done once.)
-
Fork this repository here on GitHub.
-
Clone your fork locally.
$ git clone https://github.com/YOUR_USERNAME/Cataclysm-BN.git
# Clones your fork of the repository into the current directory in terminal- Set commit message template.
$ git config --local commit.template .gitmessage- Add this repository as a remote.
$ cd Cataclysm-BN
# Changes the active directory in the prompt to the newly cloned "Cataclysm-BN" directory
$ git remote add -f upstream https://github.com/cataclysmbnteam/Cataclysm-BN.git
# Assigns the original repository to a remote called "upstream"For further details about commit message guidelines please visit:
- Make sure you have your
mainbranch checked out.
$ git checkout main- Pull the changes from the
upstream/mainbranch.
$ git pull --ff-only upstream main
# gets changes from "main" branch on the "upstream" remoteNote If this gives you an error, it means you have committed directly to your local
mainbranch. Click here for instructions on how to fix this issue.
-
Update your
mainbranch, if you haven't already. -
For each new feature or bug fix, create a new branch.
$ git branch new_feature
# Creates a new branch called "new_feature"
$ git checkout new_feature
# Makes "new_feature" the active branch- Once you've committed some changes locally, you need to push them to your fork here on GitHub.
$ git push origin new_feature
# origin was automatically set to point to your fork when you cloned it- Once you're finished working on your branch, and have committed and pushed all your changes,
submit a pull request from your
new_featurebranch to this repository'smainbranch.
Note any new commits to the
new_featurebranch on GitHub will automatically be included in the pull request, so make sure to only commit related changes to the same branch.
If you file a PR but you're still working on it, please mark it as draft. This can help speed up our review process by allowing us to only review the things that are ready for it, and will prevent anything that isn't completely ready from being merged in.
It 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.
One more thing: when marking your PR as closing, fixing, or resolving issues, please include this somewhere in the description:
- {keyword} #{issue}for example: - fixed #12345
{keyword} must be one of the following:
close,closes,closedfix,fixes,fixedresolve,resolves,resolved
and {issue} is the number of the issue you're closing after PR gets merged.
This would automatically close the issue when the PR is pulled in, and allows merges to work slightly faster.
- {keyword} #{issue}, {keyword} #{issue}See https://help.github.com/articles/closing-issues-using-keywords for more.
Various tools are available to help you keep your contributions conforming to the appropriate style. See DEVELOPER_TOOLING for more details.
These guidelines aren't essential, but they can make keeping things in order much easier.
Remote tracking branches allow you to easily stay in touch with this repository's main branch, as
they automatically know which remote branch to get changes from.
$ git branch -vv
* main xxxx [origin/main] ....
new_feature xxxx ....Here you can see we have two branches; main which is tracking origin/main, 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.
$ git checkout new_feature
Switched to branch 'new_feature'
$ git pull
There is no tracking information for the current branch.
Please specify which branch you want to merge with.In order to easily pull changes from upstream/main into the new_feature branch, we can tell git
which branch it should track. (You can even do this for your local main branch.)
$ git branch -u upstream/main new_feature
Branch new_feature set up to track remote branch main from upstream.
$ git pull
Updating xxxx..xxxx
....You can also set the tracking information at the same time as creating the branch.
$ git branch new_feature_2 --track upstream/main
Branch new_feature_2 set up to track remote branch main from upstream.Note: Although this makes it easier to pull from
upstream/main, it doesn't change anything with regards to pushing.git pushfails because you don't have permission to push toupstream/main.
$ git push
error: The requested URL returned error: 403 while accessing https://github.com/cataclysmbnteam/Cataclysm-BN.git
fatal: HTTP request failed
$ git push origin
....
To https://github.com/YOUR_USERNAME/Cataclysm-BN.git
xxxx..xxxx new_feature -> new_featureThere is a suite of tests built into the source tree at tests/ You should run the test suite after
ANY change to the game source. An 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. With no
arguments it will run the entire test suite. With --help it will print a number of invocation
options you can use to adjust its operation.
$ make
... compilation details ...
$ tests/cata_test
Starting the actual test at Fri Nov 9 04:37:03 2018
===============================================================================
All tests passed (1324684 assertions in 94 test cases)
Ended test at Fri Nov 9 04:37:45 2018
The test took 41.772 secondsI recommend habitually invoking make like make YOUR BUILD OPTIONS && make check.
Whether 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.
Bring 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:
┌─────────────────────────────────────────────────────┐
│ Debug Functions - Manipulate the fabric of reality! │
├─────────────────────────────────────────────────────┤
│ i Info │
│ Q Quit to main menu │
│ s Spawning... │
│ p Player... │
│ t Teleport... │
│ m Map... │
└─────────────────────────────────────────────────────┘
With these commands, you should be able to recreate the proper conditions to test your changes. The DDA wiki may have useful informations regarding debug menu.
If git pull --ff-only shows an error, it means that you've committed directly to your local main
branch. To fix this, we create a new branch with these commits, find the point at which we diverged
from upstream/main, and then reset main to that point.
$ git pull --ff-only upstream main
From https://github.com/cataclysmbnteam/Cataclysm-BN
* branch main -> FETCH_HEAD
fatal: Not possible to fast-forward, aborting.
$ git branch new_branch main # mark the current commit with a tmp branch
$ git merge-base main upstream/main
cc31d0... # the last commit before we committed directly to main
$ git reset --hard cc31d0....
HEAD is now at cc31d0... ...Now that main has been cleaned up, we can easily pull from upstream/main, and then continue
working on new_branch.
$ git pull --ff-only upstream main
# gets changes from the "upstream" remote for the matching branch, in this case "main"
$ git checkout new_branchFor more frequently asked questions, see the developer FAQ.