4.5 KiB
Contributing
contributions to Furnace are welcome!
Issue reports
if you find an issue with Furnace, see the Issues section.
Suggestions and other types of discussions
see the Discussions section.
DO NOT USE THE ISSUES SECTION FOR THESE - it is only for ISSUES.
Other
Getting ready
log into your Github account, and click the Fork button in the header of the project's page.
then open a terminal and clone your fork:
git clone git@github.com:USERNAME/furnace.git
(replace USERNAME
with your username)
Working
Code
bug fixes, improvements and several other things accepted.
the coding style is described here:
- indentation: two spaces. strictly spaces. do NOT use tabs.
- modified 1TBS style:
- no spaces in function calls
- spaces between arguments in function declarations
- no spaces in operations except for
||
and&&
- no space between variable name and assignment
- space between macro in string literals
- space after comment delimiter
- C++ pointer style:
void* variable
rather thanvoid *variable
- indent switch cases
- preprocessor directives not intended
- if macro comprises more than one line, indent
- no new line after
template<>
- do not use
_t
types, except for 64-bit integers andsize_t
. - prefer built-in types:
bool
signed char
orunsigned char
are 8-bit- when the type is
char
, always specify whether it is signed or not. - unspecified
char
is signed on x86 and unsigned on ARM, so yeah. - the only situation in where unspecified
char
is allowed is for C strings (const char*
).
- when the type is
short
orunsigned short
are 16-bitint
orunsigned int
are 32-bitfloat
is 32-bitdouble
is 64-bitlong long int
orunsigned long long int
are 64-bit- avoid using 64-bit numbers as I still build for 32-bit systems.
- two
long
s are required to make Windows happy. - prefer using
int64_t
oruint64_t
for this specific case.
size_t
are 32-bit or 64-bit, depending on architecture.
- in float/double operations, always use decimal and
f
if single-precision.- e.g.
1.0f
or1.0
instead of1
.
- e.g.
- prefer
NULL
overnullptr
or any other proprietary null. - only use
auto
if needed. - avoid using
goto
unless absolutely required. - use
String
forstd::string
(this is typedef'd in ta-utils.h). - prefer using operator for String (std::string) comparisons (a=="").
- if you have to work with C strings, only use safe C string operations:
- snprintf
- strncpy
- strncat
- any other operation which specifies a limit
some files (particularly the ones in src/engine/platform/sound
and extern/
) don't follow this style.
you don't have to follow this style. I will fix it after I accept your contribution.
additional guidelines:
- in general strongly avoid breaking compatibility.
- do not touch loadFur/saveFur unless you know what you're doing!
- new fields must be at the end of each block to ensure forward compatibility
- likewise, the instrument read/write functions in DivInstrument have to be handled carefully
- any change to the format requires a version bump (see
src/engine/engine.h
). - do not bump the version number under any circumstances!
- if you are making major changes to the playback routine, make sure to test with older songs to ensure nothing breaks.
- I will run a test suite to make sure this is the case.
- if something breaks, you might want to add a compatibility flag (this requires changing the format though).
- do not touch loadFur/saveFur unless you know what you're doing!
- do not use
#pragma once
. - do not memcmp() structs.
- on a switch block, always put
default
last and not in any other position.- I have fear of some C/C++ compilers ignoring the rest of cases upon hitting default.
Do NOT Force-Push after submitting Pull Request
if you do so, your pull request will be closed.
Demo Songs
just put your demo song in demos/
! be noted there are some guidelines:
- avoid Nintendo song covers.
- avoid big label song covers.
- low effort compositions/covers may not be accepted at all.
- the following systems are not acceptable:
- YMU759/MA-2: exists only for compatibility.
- Pong: it is a joke system.
- the song shall be in Furnace file format.
Finishing
after you've done your modifications, commit the changes and push. then open your fork on GitHub and send a pull request.
I don't know how to use Git but I want to contribute with a demo song
you can also contact me directly! find me here.