To develop and maintain a separate codebase is a big task, that many have failed and suffered the consequences of, such as outdated, and messy code. It's not necessarily the fault of lack of skill of the people maintaining it, merely the lack of resources and how much continuous effort such an endeavor takes.
One of the solutions for such, is to base our server on a solid codebase, that is primarily maintained by somebody else, in this case tgstation, and insert our content in a modular fashion, while following the general code (but not gameplay) direction of the upstream, mirroring any changes they do for parity.
Git, as a version control system, is very useful, however it is just a very methodical thing, that follows its many algorithms, that sadly cannot always intelligently resolve certain changes in the code in an unambiguous way, giving us conflicts, that need to be resolved in a manual fashion.
Due to maintainability being one of the main reasons behind our rebase to another codebase, this protocol will seriously be enforced. A well organized, documented and atomized code saves our maintainers a lot of headache, when being reviewed. Don't dump on them the work that you could have done yourself.
This document is meant to be updated and changed, whenever any new exceptions are added onto it. It might be worth it to check, from time to time, whether we didn't define a more unique standardized way of handling some common change.
You are responsible for the testing of your content. You should not mark a pull request ready for review until you have actually tested it. If you require a separate client for testing, you can use a guest account by logging out of BYOND and connecting to your test server. Test merges are not for bug finding, they are for stress tests where local testing simply doesn't allow for this.
For example, let's have an original
var/something = 1in the core code, that we decide to change from 1 to 2 on our end,
- var/something = 1
+ var/something = 2 //SKYRAT EDITbut then our upstream introduces a change in their codebase, changing it from 1 to 4
- var/something = 1
+ var/something = 4As easy of an example as it is, it results in a relatively simple conflict, in the form of
var/something = 2 //SKYRAT EDITwhere we pick the preferable option manually.
That is something that cannot and likely shouldn't be resolved automatically, because it might introduce errors and bugs that will be very hard to track down, not to even bring up more complex examples of conflicts, such as ones that involve changes that add, remove and move lines of code all over the place.
tl;dr it tries its best but ultimately is just a dumb program, therefore, we must ourselves do work to ensure that it can do most of the work, while minimizing the effort spent on manual involvement, in the cases where the conflicts will be inevitable.
Our answer to this is modularization of the code.
Modularization means, that most of the changes and additions we do, will be kept in a separate modular_skyrat/ folder, as independent from the core code as possible, and those which absolutely cannot be modularized, will need to be properly marked by comments, specifying where the changes start, where they end, and which feature they are a part of, but more on that in the next section.
Always start by thinking of the theme/purpose of your work. It's oftentimes a good idea to see if there isn't an already existing one, that you should append to.
If it's a tgcode-specific tweak or bugfix, first course of action should be an attempt to discuss and PR it upstream, instead of needlessly modularizing it here.
Otherwise, pick a new ID for your module. E.g. DNA-FEATURE-WINGS or XENOARCHEAOLOGY or SHUTTLE_TOGGLE - We will use this in future documentation. It is essentially your module ID. It must be uniform throughout the entire module. All references MUST be exactly the same. This is to allow for easy searching.
And then you'll want to establish your core folder that you'll be working out of which is normally your module ID. E.g. modular_skyrat/modules/shuttle_toggle
IMPORTANT: MAP CONTRIBUTION GUIDELINES HAVE BEEN UPDATED
When you are adding a new item to the map you MUST follow this procedure: Start by deciding how big of a change it is going to be, if it is a small 1 item change, you should use the simple area automapper. If it is an entire room, you should use the template automapper.
We will no longer have _skyrat map versions.
DO NOT CHANGE TG MAPS, THEY ARE HELD TO THE SAME STANDARD AS ICONS. USE THE ABOVE TO MAKE MAP EDITS.
The automapper uses prebaked templates to override sections of a map using coordinates to plot the starting location. See entries in automapper_config.toml for examples.
The simple area automapper uses datum entries to place down a single item in an area of a map that makes vauge sense.
Git doesn't handle conflicts of binary files well at all, therefore changes to core binary files are absolutely forbidden, unless you have a really really really good reason to do otherwise.
All assets added by us should be placed into the same modular folder as your code. This means everything is kept inside your module folder, sounds, icons and code files.
-
Example: You're adding a new lavaland mob.
First of all you create your modular folder. E.g.
modular_skyrat/modules/lavalandmobAnd then you'd want to create sub-folders for each component. E.g.
/codefor code and/soundsfor sound files and/iconsfor any icon files.After doing this, you'll want to set your references within the code.
/mob/lavaland/newmob icon = 'modular_skyrat/modules/lavalandmob/icons/mob.dmi' icon_state = "dead_1" sound = 'modular_skyrat/modules/lavalandmob/sounds/boom.ogg'
This ensures your code is fully modular and will make it easier for future edits.
-
Other assets, binaries and tools, should usually be handled likewise, depending on the case-by-case context. When in doubt, ask a maintainer or other contributors for tips and suggestions.
-
Any additional clothing icon files you add MUST go into the existing files in master_files clothing section.
You should always put any modular overrides of icons, sound, code, etc. inside this folder, and it must follow the core code folder layout.
Example: code/modules/mob/living/living.dm -> modular_skyrat/master_files/code/modules/mob/living/living.dm
This is to make it easier to figure out what changed about a base file without having to search through proc definitions.
It also helps prevent modules needlessly overriding the same proc multiple times. More information on these types of edits come later.
This section will be fairly straightforward, however, I will try to go over the basics and give simple examples, as the guide is aimed at new contributors likewise.
The rule of thumb is that if you don't absolutely have to, you shouldn't make any changes to core codebase files.
In short, most of the modular code will be placed in the subfolders of your main module folder modular_skyrat/modules/yourmodule/code/, with similar rules as with the assets. Do not mirror core code folder structures inside your modular folder.
For example, modular_skyrat/modules/xenoarcheaology/code containing all the code, tools, items and machinery related to it.
Such modules, unless very simple, need to have a readme.md in their folder, containing the following:
- links to the PRs that implemented this module or made any significant changes to it
- short description of the module
- list of files changed in the core code, with a short description of the change, and a list of changes in other modular files that are not part of the same module, that were necessary for this module to function properly
- (optionally) a bit more elaborative documentation for future-proofing the code, that will be useful further development and maintenance
- credits
Template: Here
Note, that it is possible to append code in front, or behind a core proc, in a modular fashion, without editing the original proc, through referring the parent proc, using ..(), in one of the following forms. And likewise, it is possible to add a new var to an existing datum or obj, without editing the core files.
These modular overrides should be kept in master_files, and you should avoid putting them inside modules as much as possible.
To keep it simple, let's assume you wanted to make guns spark when shot, for simulating muzzle flash or whatever other reasons, and you want potentially to use it with all kinds of guns.
You could start, in a modular file, by adding a var.
/obj/item/gun
var/muzzle_flash = TRUEAnd it will work just fine. Afterwards, let's say you want to check that var and spawn your sparks after firing a shot. Knowing the original proc being called by shooting is
/obj/item/gun/proc/shoot_live_shot(mob/living/user, pointblank = 0, atom/pbtarget = null, message = 1)you can define a child proc for it, that will get inserted into the inheritance chain of the related procs (big words, but in simple cases like this, you don't need to worry)
/obj/item/gun/shoot_live_shot(mob/living/user, pointblank = 0, atom/pbtarget = null, message = 1)
. = ..() //. is the default return value, we assign what the parent proc returns to it, as we call it before ours
if(muzzle_flash)
spawn_sparks(src) //For simplicity, I assume you've already made a proc for thisAnd that wraps the basics of it up.
Every once in a while, there comes a time, where editing the core files becomes inevitable.
Please be sure to log these in the module readme.md. Any file changes.
In those cases, we've decided to apply the following convention, with examples:
-
Addition:
//SKYRAT EDIT ADDITION BEGIN - SHUTTLE_TOGGLE - (Optional Reason/comment) var/adminEmergencyNoRecall = FALSE var/lastMode = SHUTTLE_IDLE var/lastCallTime = 6000 //SKYRAT EDIT ADDITION END
-
Removal:
//SKYRAT EDIT REMOVAL BEGIN - SHUTTLE_TOGGLE - (Optional Reason/comment) /* for(var/obj/docking_port/stationary/S in stationary) if(S.id = id) return S */ //SKYRAT EDIT REMOVAL END WARNING("couldn't find dock with id: [id]")
And for any removals that are moved to different files:
//SKYRAT EDIT REMOVAL BEGIN - SHUTTLE_TOGGLE - (Moved to modular_skyrat/shuttle_toggle/randomverbs.dm) /* /client/proc/admin_call_shuttle() set category = "Admin - Events" set name = "Call Shuttle" if(EMERGENCY_AT_LEAST_DOCKED) return if(!check_rights(R_ADMIN)) return var/confirm = alert(src, "You sure?", "Confirm", "Yes", "No") if(confirm != "Yes") return SSshuttle.emergency.request() SSblackbox.record_feedback("tally", "admin_verb", 1, "Call Shuttle") //If you are copy-pasting this, ensure the 2nd parameter is unique to the new proc! log_admin("[key_name(usr)] admin-called the emergency shuttle.") message_admins(span_adminnotice("[key_name_admin(usr)] admin-called the emergency shuttle.")) return */ //SKYRAT EDIT REMOVAL END
-
Change:
//SKYRAT EDIT CHANGE BEGIN - SHUTTLE_TOGGLE - (Optional Reason/comment) //if(SHUTTLE_STRANDED, SHUTTLE_ESCAPE) - SKYRAT EDIT - ORIGINAL if(SHUTTLE_STRANDED, SHUTTLE_ESCAPE, SHUTTLE_DISABLED) //SKYRAT EDIT CHANGE END return 1
From every rule, there's exceptions, due to many circumstances. Don't think about it too much.
Due to the way byond loads files, it has become necessary to make a different folder for handling our modular defines.
That folder is code/__DEFINES/~skyrat_defines, in which you can add them to the existing files, or create those files as necessary.
If you have a define that's used in more than one file, it must be declared here.
If you have a define that's used in one file, and won't be used anywhere else, declare it at the top, and #undef MY_DEFINE at the bottom of the file. This is to keep context menus clean, and to prevent confusion by those using IDEs with autocomplete.
To keep form and ensure most modules are easy to navigate and to keep control of the amount of files and folders being made in the repository, you are required to follow this layout.
Ensure the folder names are exactly as stated.
Top most folder: module_id
DO NOT COPY THE CORE CODE FILE STRUCTURE IN YOUR MODULE!!
Code: Any .DM files must go in here.
- Good: /modular_skyrat/modules/example_module/code/disease_mob.dm
- Bad: /modular_skyrat/modules/example_module/code/modules/antagonists/disease/disease_mob.dm
Icons: Any .DMI files must go in here.
- Good: /modular_skyrat/modules/example_module/icons/mining_righthand.dmi
- Bad: /modular_skyrat/modules/example_module/icons/mob/inhands/equipment/mining_righthand.dmi
Sound: Any SOUND files must go in here.
- Good: See above.
- Bad: See above.
The readme should go into the parent folder, module_id.
DO NOT MIX AND MATCH FILE TYPES IN FOLDERS!
If you are commenting out redundant code in modules, do not comment it out, instead, delete it.
Even if you think someone is going to redo whatever it is you're commenting out, don't, gitblame exists for a reason.
This also applies to files, do not comment out entire files, just delete them instead. This helps us keep down on filebloat and pointless comments.
This does not apply to non-modular changes.
Here are a couple PR's that are great examples of the guide being followed, reference them if you are stuck:
It might seem like a lot to take in, but if we remain consistent, it will save us a lot of headache in the long run, once we start having to resolve conflicts manually. Thanks to a bit more scrupulous documentation, it will be immediately obvious what changes were done and where and by which features, things will be a lot less ambiguous and messy.
Best of luck in your coding. Remember that the community is there for you, if you ever need help.