Skip to content

Latest commit

 

History

History
424 lines (282 loc) · 29.3 KB

CONTRIBUTING.md

File metadata and controls

424 lines (282 loc) · 29.3 KB
Raw

Are you here because you want to:

Table of Contents

How to Report Bugs

Bug reports are a very valuable contribution to the development of this mod - but only if done right.

"Kerbalism doesn't work" is not a good bug report, because it sure works well for me. If it doesn't work for you, it is your responsibility to make clear which conditions lead to stuff going wrong. Good bug reports are effort and require time - but putting in that effort helps immensely to not waste developer time and get the bug fixed quickly.

All bugs should be reported on GitHub, under this URL: https://github.com/Kerbalism/Kerbalism/issues

You are free to mention any issues on the forum thread, but in the end, all issues must be registered on GitHub. This is because we use GitHub as a workflow management tool and the issues list as a checklist, and all the information and discussions for one specific issue are in one place as opposed to getting buried under posts in the forums.

All bug reports must contain the following information:

  • Which version of Kerbalism are you using? If in doubt, check out the Kerbalism.version file in GameData\Kerbalism
  • Which version of KSP are you using?
  • Which mods are you running, and which versions do they have? Please note that when reporting a bug, you should only ever have the minimal amount of mods installed that are necessary to reproduce the bug (see below for tips on removing mods).
  • The output_log.txt file, from the KSP_x64_Dataor KSP_Data directory. You can either zip it and directly attach it to the bug report or upload to a pastebin service.

If you encounter problems with specific vessels, please attach the craft file and short instructions on how to use it. Remove parts from Mods so we can load them, unless the parts from Mods are crucial for reproducing the problem.

It is recommended to attach Quicksave files that describe the situation. Again, make sure that we can load them and remove all non-Stock crafts (unless they are crucial for the reproduction).

Make clear which conditions have led to the bug: what exactly did you do? What makes the bug go away (workaround), what makes it appear? Some experimentation on your part is very appreciated, so that we can find the problem more easily.

More on reporting bugs for KSP mods can be found in this forum topic: http://forum.kerbalspaceprogram.com/index.php?/topic/83212

Removing Mods for Debugging

When reporting issues for any mod, your first action should be to cull the list of your mods to the minimal amount of mods where the issue still occurs. Most of the time, this means there will be no mods except Kerbalism.

The very first thing you should do is to back up your save file!!! We are not responsible for lost save files. To do this, go into the "saves" folder, right-click on your save with the right name, click Send To -> Zip Compressed folder. Don't do anything before you did that.

Next, create a backup of your GameData folder (Excluding "Squad"), and delete all mods in there except for Kerbalism and ModuleManager (and Squad obviously).

Create a new Savegame, build a craft with Stock parts that triggers the problem and launch it. Don't be afraid to use the Cheat menu to get the craft into the situation that you need (Set orbit, rendezvous, infinite fuel...). In the animal kingdom, Alpacas of the "dirty cheating" variety are the most successful when it comes to debugging.

Most of the time the bug will occur with only Kerbalism installed.

Sometimes, you will require other mods to reproduce it, such as FAR or RSS. In that case, try to delete all mods that are uninvolved and state clearly which mods (and which versions of them) are required.

If you are sure that the problem doesn't happen with only Kerbalism but don't know which is responsible, you have to search for it. The simplest method is to add mods one by one. If you have few installed, you should do that.

However, "binary search" is more effective: Add half your mods and see if the problem occurs. If not, add the other half. If yes, split the first half again and add the first quarter. If that doesn't cause the problem, remove it again and add the second quarter. Keep halving the number of mods that you are testing until you arrived at one single mod. This might sound complicated, but if you have a big number of mods, you will find the culprit a lot faster than by linear search.

How to Suggest Features

While we value all input and suggestions for improvement, a few things should be considered to make sure that your suggestion is understood and to increase the chances of adoption.

Stay Polite

Never forget that all contributors and maintainers are doing this Mod for fun, and do not get paid. If you want a feature, it is in your best interest to remain on good terms with the contributors and keep them motivated to work on the project.

Therefor, it is also in your best interest to not demand features, to not pressure us to implement a feature and not to insult any previous work - that includes not crapping on the current state of affairs, no matter how frustrated you might be.

In German there is a saying:

Der Ton macht die Musik

Which is literally translated to "the tone makes the music" and means that the tone of conversation is paramount to reach a good result. A demanding or bitter tone is a sure way to shut down even the best intentioned request. Stay polite and keep your tone positive.

Consider the workload

As mentioned, none of us get paid to work on this project. Please consider this, when you try to suggest features that take a lot of work. Even the best idea in the world might not be implemented, simply because there is nobody around with the time to implement it.

This shouldn't prevent you from making it in the first place, but try to asses how much work a feature would be, state that in your suggestion, and don't be too disappointed if it's doesn't get implemented.

What would be best, of course, is to implement the feature yourself and submit a pull request! We have a guide for new contributors right here.

Gather feedback from the community

When you are requesting a feature, even when it is for "personal use", it can still be good to bring in the community. Suggest the feature on the Forums, ask for Feedback from other users, create an issue on GitHub. Be responsive, and accept feedback and suggestions to make your suggestion even better ;)

Make sure that the feature is wanted

An important part of gathering feedback is: is your feature even necessary? Sometimes when you think that you can't live without a certain feature or change, it is good to ask the community: is there a way to achieve the desired result with current tools?

Ask other users if they also believe that this feature is necessary, and gather support. When many users claim that they want something, the chances of adoption increase (but there's still no guarantee!).

Consider the Impact

Whenever a new feature is introduced, no matter how big the benefits, there are some drawbacks as well. This includes (but is not limited to) the following:

  • Performance: every calculation takes time, needs a processor to execute it and consumes energy. Consider that your feature will potentially run on many users machines, for multiple hours, for around 30 times per second. You don't want to be the guy who's responsible for melting our planets ice caps, are you? ;) Sometimes this is negligible. Sometimes, it is not. Think about which it is when you suggest a feature.
  • Changing workloads: People are creatures of habit, and so are this mods users. When you introduce a change in "the way they do things", be aware that many people (who your are currently unaware of, because they are content and happy) will suddenly have to change their behavior and that they might not be as happy about the change as you are.

When you submit a feature request, please make sure to think about the drawbacks that your feature could have and specify and explain them clearly.

Why can't you just add a toggle

If your feature request would introduce a change that makes the Mod do something differently, you might be tempted to add toggles and switches to revert back to the old behavior, or when your feature is rejected because of the impact it has, you might exclaim "why can't you just add a toggle?". No, generally we can't. Here is why:

While it might make perfect sense from an individual point of view, where you consider one single feature and one single switch, changing the perspective to that of the maintainer makes things more complicated.

A maintainer has to consider the entirety of all switches, options and toggles. What is "just one more switch" for you might be the twenty first switch to the maintainer. While there is undoubtedly value in a "configurable" product, it also incurs a cost!

  • It's harder to learn how the mod works, harder to write manuals and therefor produces more support requests.
  • Adding switches requires an increased amount of testing. If we had a testing matrix, adding switches increases the workload quadratically! (But we don't, so that point is a bit moot.)
  • Adding switches increases the complexity of code, adds more corner situations, more potential for bugs and makes debugging harder (not least because it's yet another thing that users have to specify)
  • A program full of toggle buttons, half of which are in the same state for most users for most of the time anyway is plain ugly.

Last but not least, we have to consider the overall "usability" of the mod, the "feel" of the mod and the "user stories". When adding a feature, we should not take the cheap and easy way out ("just add a toggle"), but think about how people use the mod and how to make their lives better. Sometimes it might be better to change the user experience completely or even remove features to avoid confusion.

What not to suggest

Some features have been suggested many times, but cannot be included for technical reasons and why they will probably never make it into Kerbalism.

If you disagree with this assessment, the best way to convince us otherwise is to provide a working implementation that fits well with the rest of the mod.

Where to suggest a feature

Please suggest features by posting both in the Forum thread (so that users can also participate in the discussion) and create a GitHub issue on our tracker.

Make sure to explain the purpose of this feature, the advantages and the potential impact on the mod.

Please try to also think of a way how to implement the feature in a way that makes sense both from the users and the developers perspective.

Learn to accept a No

Sometimes, requests cannot be met - either because they don't match the Mods core idea or because their impact is too high or simply because the contributors don't have enough time.

Consider forking the project and implementing the feature into your private builds, and playing with it in your private game. With more experience and testing and even "finished" code, your case for adoption into the main mod is a lot stronger! Even if that doesn't work, you'll have the feature for yourself ;)

If after all has been said and discussed and weighed the community or the maintainers have come to the conclusion that your suggestion doesn't fit the bill, please accept that and move on. Do not start to repeat yourself - this only serves to poison the discussion.

This is not a reason to be discouraged, your suggestion is still considered valuable!

How to Contribute

Are you a pro and know all the things already? Here's are the links to the info specific to Kerbalism:

Where to Start

If you like using the Kerbalism mod, please consider contributing!

There are many ways to contribute to the mod:

  • Write documentation! We could use a good manual, better code comments, an API documentation inside the code.
  • Report bugs - but do it well. Well-written bug reports are very appreciated. Make sure to follow the guidelines above.
  • Help testing, reproducing and narrowing down existing bugs
  • Help with code-cleanup, make the code more readable, reduce inefficiencies (but make sure you don't break anything!)
  • Write new features! We have a few much-requested features on our issue tracker that you could implement. Or, just solve your pet problem!

Especially before writing new features, communication is paramount! Please visit our forum thread, let other people know what you are working on, ask for Feedback, talk about the mod. This is crucial to avoid merge conflicts, duplicated or unnecessary work.

Using Git and GitHub

Git is a distributed version control system used by a myriad of projects, including big players like the Linux Kernel, Android or even Windows! While Git in its simplest form is "only" a version control system, it also enables collaboration in a way that no other version control system ever could.

To aid with this collaboration GitHub was created. GitHub is first and foremost a hoster for Git repositories. But it also includes tools for bug tracking, documentation, and even some light project management.

If you want to contribute to the Kerbalism Mod, it is highly recommended to familiarize yourself with Git and GitHub. Luckily, there are many good guides out there.

If you want to get into the depths of Git, this (online) book is recommended:

Note: Git itself is a command line tool and has many many commands and options. This can be a bit daunting, so tools were created to help with that. You can use GitHub Desktop to do many tasks that can be done on the command line.

Personally, I find that these tools don't offer the fine-grained control that I came to expect from the command line tools. In the future, you should consider learning the intricacies of Git in its entirety. It'll probably give you bonus points in your next interview ;)

Workflow for the Kerbalism mod

To start contributing, you have to first set up your Kerbalism repository by forking it.

Before doing any work, you should create and switch to a branch. The name of the branch should reflect the "topic" of your work (these are often called "topic branches"). If you want to work on multiple areas/topics at the same time, it is better to create multiple branches! Don't just mush all of your work into one single branch.

Commit your work early and often! It's better to have too many commits than to lose work.

  • For Git pro users: Before making a pull request, please Squash your commits into more-or-less consistent, self-contained chunks that can be reverted if necessary.
  • For Git novices: Please do not squash your commits! The risk of losing your work is too high, so please just make your pull request and we'll take it from there.

When you are finished with your work, it is possible that work on the master branch has moved on. To simplify the merge process, you should make sure that your branch is merge-able. Try merging your topic branch into the most up-to-date master branch (from the main repository, not from your fork!). Make sure that you actually build and test the mod, don't just assume that "it's fine".

If you get merge conflicts, please resolve them before submitting a pull request. If you are having trouble with that, speak up! Other contributers can help you with the merge process, and it's no shame especially since resolving merge conflicts is tricky.

  • For Git pro users: Please rebase your pull request branches on the latest master branch.
  • For Git novices: Please do not rebase anything! The risk of losing your work is too high, so please just make your pull request and we'll take it from there.

How to submit pull requests

A pull request is a request from a contributor (you) to the maintainer (me) for inclusion of the contributors changes into the master branch of the main repository. While your time spent on contributions is valuable and much appreciated, please consider that the time spent by the maintainer on reviewing, testing and merging your changes is also valuable.

To ensure smooth sailing with pull requests, please follow these guidelines:

  • Communicate early on what you are working. Let other people know what you are up to, explain what you want to do and why. Gather Feedback! This is crucial to avoid merge conflicts, duplicated or unnecessary work. The mod forum thread is a good place for that.
  • Don't submit your master branch, only submit named feature branches!
  • Keep the code compilable and working!
  • Do sufficient testing to make sure that no new bugs are introduced. Since we neither have a QA department nor a test suite, testing will be manual. It is recommended to use your version of the Mod in your main KSP save for a while, before submitting a pull request.
  • Be considerate of our users KSP installs! We are most likely not gonna be the only mod in KSP's memory space, so make sure your changes don't deteriorate performance, use too much memory and don't cause crashes!
  • In your pull request, please explain your changes, why they are necessary and how they make Kerbalism better.
  • If you are adding a feature, please provide a little section of text that could go into a manual.
  • Please follow the code style guidelines
  • Please submit readable, high-quality code!

Once you followed the guidelines above, please submit your pull request to the main repository. Please select "allow edits from maintainers" so that the maintainer can help you with your pull request.

Adding commits after you submitted the pull request is not forbidden - after all, if you gotta change something, you gotta change something. However, please make sure that your pull request is complete and high-quality before submitting it. If you find an oversight after submitting it, please make abundantly clear what you changed after you add commits.

Code Style

We currently target the C# version 7.1.

Please observe some basic style rules for your contributions:

  • Follow the naming guidelines put out by Microsoft
  • Per indentation level, use 4 spaces and no tabs
  • Use Carriage-Return & Line Feed (CRLF) line endings in all C# and Visual Studio source code files. Source files or config files for tools that do not work on Windows and/or can't handle CRLF line endings are exempt.
  • Avoid trailing whitespace
  • Please document your code briefly with inline-comments. If you add new functions, provide summaries that explain parameters, return values and side effects.

Setup guide

Kerbalism uses a custom build and deployment system. From your IDE, don't try to change the project references and don't change anything in the project properties, that won't work.

Project Setup

Before you can build Kerbalism, your IDE has to know where the Unity and KSP assemblies are, and what version of KSP you are using.

This is done by editing a configuration file :

  • Close your IDE (Visual Studio or Monodevelop)
  • In you file explorer, go to the BuildSystem folder
  • Make a copy of the UserConfigDevEnv.xml.CopyMe file and rename it to UserConfigDevEnv.xml
  • Open this file in a text editor and follow the instructions in the comments.
  • Save the file
  • Open you IDE and make sure you are in the Debug configuration

The release configuration require a special setup, ask us first if you really need to build it.

Debugging

Note that the following steps are specific to Windows and Visual Studio 2017+. The steps here are specific to Windows and Visual Studio 2017+ but they should be more or less similar on OSX / Linux. There is some information available at this KSP forums thread

Note that live debugging on OSX / Linux is only possible since KSP 1.8

To be able to place breakpoint and use the debugging functions of Visual Studio, you need to :

  • Modify your KSP installation to use the unity player instead of the KSP executable
  • Install the Visual Studio Tools for Unity extension

Downloading the Unity player

You will need to download and install the exact version of Unity Editor that was used to build the version of KSP you are working with.

For KSP 1.4 to 1.7 the Unity version is Unity v2017.1.3p1 For KSP 1.8+ the Unity version is Unity v2019.2.2f1 You can download the unity editor from the Unity download archive

Creating a KSP dev install

You should create a KSP install just for development that is separate from your install that you use for gaming.

To do that, follow these steps:

  • Copy your game install to another location

  • Find your Unity install, and go into the subdirectory Unity\Editor\Data\PlaybackEngines\windowsstandalonesupport\Variations\win64_development_mono.

  • [KSP 1.4 to 1.7] Copy the file player_win.exe from the win64_development_mono folder to your KSP install root directory.

  • [KSP 1.4 to 1.7] Rename player_win.exe to KSP_x64_Dbg.exe.

  • [KSP 1.4 to 1.7] Copy the PlayerConnectionConfigFile file available in the Kerbalism repository in BuildSystem\DevEnvInstall\Windows and put it into your KSP dev KSP_x64_Data folder.

  • [KSP 1.8+] Copy the WindowsPlayer.exe, UnityPlayer.dll and WinPixEventRuntime.dll from the win64_development_mono folder to your KSP install root directory. You need to overwrite the original UnityPlayer.dll.

  • [KSP 1.8+] Rename WindowsPlayer.exe to KSP_x64_Dbg.exe.

  • [KSP 1.8+] Edit the KSP_x64_Data\boot.config file in a text editor and add the following line : player-connection-debug=1

  • Create a junction in your KSP dev install folder named KSP_x64_Dbg_Data linking to your KSP dev KSP_x64_Data folder. This is done by opening a command prompt in your KSP dev install folder and running the following command:

    `mklink /J KSP_x64_Dbg_Data KSP_x64_Data`

Now you can choose between the debuggable version (launch KSP_x64_Dbg.exe) and the normal version (run KSP_x64.exe).

Build and debug in Visual Studio

First, install the Visual Studio Tools for Unity from the Tools->Extensions and Updates menu in Visual Studio.

Make sure you are in the debug configuration and click on the green "start" button.

Then, go to "Debug -> Attach Unity Debugger" from the Visual Studio menu, and then select the "WindowsPlayer" process. If the "WindowsPlayer" process doesn't show up in this menu, check that both KSP and Visual Studio are allowed to communicate through the local firewall.

You should now be able to create breakpoints, step through the execution and inspect variables. If that doesn't happen (the debugger just doesn't halt where you want it to), make sure that the debugging symbols (.mdb or .pdb depending on your KSP version) are available in the GameData directory, along with the Kerbalism.dll file.

Note that while you are halting at a breakpoint, the KSP will become unresponsive. If you try to open it while halted, Windows will suggest to kill it. This is not what you want when debugging ;)

Tips on debugging

To debug KSP, you have to enable the "Background Simulation" option inside the game, by going to KSP Main Menu -> Settings -> General -> Simulate In Background and setting it to ON. It is recommended to debug KSP in a window rather than fullscreen, so turn off full screen by going to KSP Main Menu -> Settings -> Graphics and unchecking "Full screen". To save startup time, seconds of our life and the environment, it is recommended to set the Graphics options way down.

Profiling

Unity Profiler

You can use the Unity Editor profiler by starting the Unity Editor, opening a blank project (or any project for that matter) and then use the Window Menu->Profiler option to open the Profiler Window. Now you can start your KSP dev install debug executable either standalone or with Visual Studio.

By default you will only see the MonoBehavior methods (Update, FixedUpdate, etc...) but you can add calls in your code to profile anything you like. To do this, add to your code pairs of Profiler.BeginSample("MyLabel"); and Profiler.EndSample();. Be aware that if a frame takes too long to execute the profiler will skip it.

For more information see the KSP Forum thread KSP Plugin debugging and profiling for Visual Studio and Monodevelop on all OS.

Internal Profiler

In addition, there is a simple "frame-based" profiler included in the KSP Kerbalism code base, that is appropriate for quick performance measurements.

In the code, wrap the code you want in pairs of Kerbalism.Profiler.Start("MyLabel") and Kerbalism.Profiler.Stop("MyLabel").

In-game, start it by pressing Ctrl-P. It shows each code entry belonging to one label as one line. The columns show:

  • NAME: The Label for the code being profiled.
  • LAST: Code runtime for a call in the last executed frame.
  • AVG: Code runtime averaged over all the calls since start or reset.
  • CALLS: Number of calls in the last executed frame.
  • AVG: Number of calls divided by the number of frames since start or reset.

You can reset these counters with the Reset button. You can enable/disable the display of any calls not called in the last frame with the Show zero calls button.

OBSOLETE - Release Checklist

  • Complete the CHANGELOG.md file, and fill out the release date field. Make sure to credit all contributors.
  • Adjust the compatible KSP version numbers in Kerbalism.version. Actually test if they work in all the KSP version claimed compatible.
  • Bump the version number in Kerbalism.version and Properties\AssemblyInfo.cs according the the versioning rules below.
  • Check with Git that your working directory is clean. No Changes are allowed, everything must be committed.
  • Build the Project in release mode
  • Clean out the GameData folder of your KSP install, only the ´Squad` folder should remain.
  • Extract the Kerbalism-<version>.zip that was created during the Release build into your GameData folder
  • Launch KSP in the non-Developer mode and verify the functionality. Check the output_log.txt for errors.
  • Create a Tag with Git, push all commits and the tag to GitHub.
  • On GitHub, draft a new release selecting the newly created tag
  • Upload the Kerbalism-<version>.zip file to GitHub, paste the changelog there
  • On SpaceDock, draft a new release and upload the Kerbalism-<version>.zip.
  • On the KSP forums, create a new post with the changelog and links to both GitHub and SpaceDock.
  • On http://ksp-avc.cybutek.net, update the version and compatibility numbers according to the AVC version file