Change background image
  1. This site uses cookies. By continuing to use this site, you are agreeing to our use of cookies. Learn More.

How 2 Code 4 Bay

Discussion in 'Coding' started by Atlantis, Jul 10, 2015.

  1. Atlantis

    Atlantis Retired Staff

    DISCLAIMER: It's written from my subjective point of view. I do not guarantee 100% accuracy of this information, as things may change in future. I will try to keep the guide updated. This guide mostly aims at people that already know how to code basic things in DM. I will mostly cover Git and GitHub related things, as well as few other things you should know, but actual code examples won't be part of this. If you have any suggestions on how to expand the guide, post under this or yell at me via messages to fix/add it.

    To contribute to baystation12 code you need following things:
    • Knowledge of how BYOND DM language works. I won't explain this thoroughly in this topic. More info on the wiki.
    • Git client. I will use SourceTree in this guide as it offers visual interface suitable for beginners, but there are more clients out there. You can use classic console-based git too. There are also other Git clients with GUI.
    • Idea. If you are creating new feature, try to suggest it on the Suggestions and Feedback forum first.
    • GitHub account.

    Your idea
    When working on code for first time, try to focus on something small. Generally speaking, try asking yourself, what if this never existed in game? Will the game work? If the answer is no try finding something else to begin with. Espicially avoid the Forbidden Code, which would be mainly Atmospherics, mob Life(), Power, Medical system, etc. Good examples are small things: New ammo type, new weapon, generally RP things (smokables, alcohol varieties, new meals, etc.). If your feature is something larger that can have actual impact on game, let's say, changes to engine layout, chemistry changes, research changes, etc. try to create topic describing your change in Suggestions and Feedback forum to see what other people think about your idea.

    First of all, remember, Git is not GitHub. Git is tool used to manage code, while GitHub is repository for mentioned code. I assume you already have an account on GitHub, if you don't have one, create it now and log in. Open baystation12's github page and click the "Fork" button close to the top-right corner of the page. That will create your personal copy of baystation12's code. Keep the page open, you will need it in a while.

    SourceTree Configuration
    As i said above, i will be using sourcetree as my Git client. I assume you already successfully installed it. First of all, open it. There are few buttons on top of the window. Go to File - Clone/New. This will allow you to clone the repository from GitHub. Go back to your browser. You should see HTTPS Clone URL (click to see how it looks) on right side of the page. Copy the URL. It will be similar to this:
    In my case, my github name is atlantiscze. Your link will therefore be different. Go back to SourceTree and paste this link into Source Path/URL field. Change Destination Path to location where you want to have your code stored. I personally prefer "C:/Baycode/" or similar path, but this is entirely matter of your personal preference. Once you are finished, click Clone. This will take some time, depending on your internet connection. SourceTree will download the code to specified folder.

    Wait until it is completed, then head to Tools - Options (on top panel) and set the Full Name and Email Address fields. You don't have to use same address and name as you use on GitHub. Save the changes. You are almost done. This is an example how your SourceTree window should look. Right click next to the Remotes tab in the middle and select "New Remote". Click the Add button. Currently, SourceTree only knows your personal fork (which is called "origin" by default), but you will need it to know Baystation12 in future. Fill out name, i personally call it "bay", you may choose anything else. Leave default remote option unchecked, and copy-paste the following into URL / Path field.
    And confirm it. Your Remotes tab should now show new remote - "Bay" in my case. Click the big "FETCH" button on top of the screen and let it run. This might not be necessary, but do it just in case. Now open the "origin" entry in your remotes tab by clicking on "+" next to it. Rightclick "Dev" and choose checkout. Confirm and let it run.

    Now navigate to the folder which contains your code. In my case it will be C:/Baycode/. Go to "tools" folder. We use two nice tools that make your life much easier. JMerge and dmitool. Both are capable of handling most conflicts in maps or dmi files. Open dmitool folder and run the installation script (git_merge_installer.bat or .sh, depending on your operating system). Go back to tools folder and do the same for JMerge folder. That's it, you are done! If you configured everything properly you won't have to do this again in the future.

    (part 1/2)
    Last edited: Jul 31, 2017
  2. Atlantis

    Atlantis Retired Staff

    Making your changes
    Creating a branch
    First, make sure that Dev is selected (displayed in bold text) in the Branches tab. Click the large "pull" button in the top menu, and set the pull from remote field to "bay" (or however you called the baystation's remote earlier). Then set the remote branch to pull field to "dev", and confirm the dialog with OK button. It may run for a while, depending on how old your local copy is. Once the command finishes your local copy will be up to date with newest Baystation code.

    Look back at the Branches tab, and right click the Dev entry. Select "New Branch". Ensure Dev remains selected while you do this. Sourcetree will ask you for branch name. If you plan to create lots of things, try to keep branch names descriptive, it really helps. You can also add date timestamp, something like 2015-07-05-.... - this helps greatly, as your branches will be ordered by date of creation. Since i am creating new weapon - Bazooka - i'll use the following name: "2015-07-05-adds-bazooka" in our example. Feel free to be more creative than me, however. Confirm this and let it create your new branch. This is where your actual changes will be stored.

    Editing the code
    You can now open baystation12.dme file in your code folder and begin coding! When you finish your project, always recompile (Control + K shortcut). Ensure it always says "0 Errors 0 Warnings". If either of these is not 0, something is bad. Fix it before continuing. Even if you make a little change, recompile. You never know, you might have made small typo, or accidentally left unclosed brackets somewhere in the code. Anything like that can cause compilation errors. You might want to read the "Coding Standards" part too. After you are 110% certain that your code works and is bug-free, commit it (this is covered later in this guide).

    Creating changelog entry
    Changelog entry ensures that players are aware of your changes. It's nice that you created a new machine, but what if nobody else knows it exists? Changelog helps with this. Go to: "YourCodeFolder/html/changelogs/" and create a copy of file example.yml. Rename it. A good name is "YourName - FeatureName", in above example "Atlantiscze - Bazooka". Now open the file, any text editor such as notepad should be enough. Change the "author" line to your name, and modify/add/remove lines in changes to describe your feature. Read the file for more information.

    Creating commit
    To do this, go back to SourceTree and click "Working Copy" in file status tab, right above the branch list. This will show which files were changed. I strongly reccomend closing DM editor before doing this, to ensure all changes are saved. Use the checkboxes next to files to add them to your commit. Never add "" file! You can also use panel on right side to select which specific segments of code in said file to commit. You won't need this in most cases. If you created a changelog entry above, add it too. Now click the Commit Message box on bottom side of the window and fill out description of your changes. Generally, the more things you changed, the more descriptive you should be. I prefer following style, but it is entirely up to you:
    Check "Push changes immediately to.." option and click Commit. It is possible that SourceTree will ask for GitHub login details. If yes, provide them, it will remember them in future. If you managed to set up everything correctly it will push the changes. You can now go back to GitHub and open a pull request.

    Creating pull request
    GitHub is quite clever, and will offer you the "Create pull request" option on the main page if you recently pushed commit to new branch. In case it does not provide the link, press the green button with two arrows or use this link. I will assume you used the button or link. First click the "Compare across forks" option to enable it. It right below the giant "Compare changes" text. It should show four selection boxes under itself: Base Fork, Base, Head Fork and Head. Leave Base Fork unchanged. Base should be whatever branch you changed, in above example it would be Dev. Head fork should be in format yourgithubname/Baystation12. You might have to find it in the list. Compare should be the branch name you specified above. In above case it will be "2015-07-05-adds-bazooka". Some of these fields may already be pre-filled for you by GitHub. If you don't see two large text boxes (one for name, second for description) click create pull request, it should show them, and even fill them out if you added only single commit.

    Either way, ensure these are filled out. Include as much information as necessary for someone else to understand what you are trying to achieve. If your feature contains new UI, machine, clothes, etc. you might want to add a screenshot or two. When you are done, click the Create pull request button. Developers will review your request and (hopefully) merge it. They might also have some requests or recommendations, which you should add to your code. Any commits added before pull request is merged will be added to it.

    Coding Standards
    I shamelessly stol... borrowed this from original forum post. If any developer wants to change these, go on. Just those few i remember:
    • Always use absolute paths when declaring procedures and globally used variables. This is an example. Top is absolute path, bottom is relative. Avoid relative paths when you can. They make searching for definitions much harder.
    • Properly comment your code. Generally, the more complicated a procedure is, the more commented it should be. Procedure called get_stored_charge() for battery is quite self-descriptive. Procedure calculate_thermal_capacity() sounds slightly more complicated and should probably have a comment or two.
    • Properly name your variables and procedures. While procedure name "process_related_machine_stuff()" will work, anyone else looking at your code will probably have no idea what that procedure does. "process_network()" is more descriptive. The same applies for variables, avoid variable names with excessive creativity. "var/my_cats_favorite_colour" and instead use descriptive names. Try to avoid very short names ("var/A", "var/DSB", etc.), espicially if they use commonly unknown shortcuts. An exception might be temporary variables in loops, etc.
    • When coding something larger include changelog entry in your PR.
    • When in doubt, ask! We have IRC for that, or this forum.

    There is an IRC channel on SorceryNet specifically for development purposes. You can find most developers there, as well as many other people that help with the code. This channel is called #codershuttle. You can also join #bs12 to talk about code-unrelated stuff.

    The End
    There is much i didn't cover in this guide. Handling merge conflicts, working with maps, etc. When in doubt, stop by on IRC, people there (almost always) know what to do and can help you out. We all started like that.
    (part 2/2)
    Last edited: Jul 31, 2017
  3. Head

    Head Retired Staff

    Eh, Could you please rework your formatting, its hard to read.
  4. Atlantis

    Atlantis Retired Staff

    I tried to tidy it up a little, tell me if there is anything specific you'd recommend to be changed.
  5. Head

    Head Retired Staff

    You need more line-breaks in the text.
  6. Loaf

    Loaf Retired Staff

    For clarity, the file is used by Dream Maker to decide what information goes into the .dme. If you commit it, your code will fail the automated compile checking and your PR will be unmergable.
  7. GinjaNinja32

    GinjaNinja32 Executive Officer

    Should probably add something in here about changelogs, or at least link to a separate "how to changelog" thread.
  8. HarpyEagle

    HarpyEagle Research Director

    I'm wondering, what do people think about making it policy to include changelog ymls with feature PRs? At the very least it would force me to stop forgetting to add them...
  9. GinjaNinja32

    GinjaNinja32 Executive Officer

    If a feature comes up without changelog and I remember, I'm poking people for them.
  10. Atlantis

    Atlantis Retired Staff

    I'll add the changelog line. Regarding mandatory changelogs - I don't think they are necessary everywhere, small 5-line fixes or other minor stuff where changelog's size would exceed actual amount of changes. I'm all for having changelogs mandatory for larger things and features.

    EDIT: Changelog info added.
    Last edited: Jul 12, 2015
  11. GinjaNinja32

    GinjaNinja32 Executive Officer

    If it affects players, IMO it needs a changelog. A minor fix for a system that's almost brand new? Nah. Major bugfix that pretty much everyone knows is a bug? Changelog "fixed X". New shiny things? Changelog.
  12. HarpyEagle

    HarpyEagle Research Director

    Oh yeah, we shouldn't have change logs for thing things that aren't player-facing, like code cleanup or fixes for things that haven't even been released yet. Every feature PR should have a changelog though.
  13. Superbee29

    Superbee29 Sol Gov Pilot

    Do you want the changelog in some file or just git?
  14. daranz

    daranz Sol Gov Pilot

    These days, we have a fancy auto-changelog system that generates changelog entries from yaml files. An example entry is in /html/changelogs/example.yml. You drop your own yaml files in /html/changelogs itself.

    dev actually has a readme for the process
    Last edited: Jul 12, 2015
  15. Atlantis

    Atlantis Retired Staff

    Kind of udpated this, the three-branch system isn't really a thing anymore.