Difference between revisions of "Guide to Changelogs"

From /tg/station 13 Wiki
Jump to navigation Jump to search
m (Remove "Game Resources" category)
 
(5 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 +
: [[Guide to contributing to the game]]
 +
 +
You can add changelog entries by using the following template in the body of your pull request:
 +
 +
:cl:
 +
prefix: text
 +
prefix: text
 +
prefix: text
 +
/:cl:
 +
 +
Your GitHub username is credited by default, or you can add a name at the end of the <tt>:cl:</tt> line to override it.
 +
 +
Valid prefixes are:
 +
 +
* [[File:Tick-circle.png]] add
 +
* [[File:Cross-circle.png]] del
 +
* [[File:Bug-minus.png]] fix
 +
* [[File:Hard-hat-exclamation.png]] wip
 +
* [[File:Wrench-screwdriver.png]] tweak
 +
* [[File:Burn-exclamation.png]] experiment
 +
* [[File:Spell-check.png]] spellcheck
 +
* [[File:Music-plus.png]] soundadd
 +
* [[File:Music-minus.png]] sounddel
 +
* [[File:Image-plus.png]] imageadd
 +
* [[File:Image-minus.png]] imagedel
 +
* [[File:Scales_icon.png]] balance
 +
* [[File:Coding.png]] code
 +
* [[File:Burn-exclamation.png]] refactor
 +
* [[File:Chrome-wrench.gif]] config
 +
* [[File:Ban.png]] admin
 +
* [[File:Hard-hat-exclamation.png]] server
 +
 +
 +
== Advanced information ==
 
{{note|This guide thanks to friends from [http://ss13.nexisonline.net/wiki/Guide_to_Changelogs /vg/].}}
 
{{note|This guide thanks to friends from [http://ss13.nexisonline.net/wiki/Guide_to_Changelogs /vg/].}}
  
 
Changelogs are small YAML files that developers create to add their pull requests' changes to the master changelog.html file.  A python script run by a maintainer collects all the changes specified and generates the HTML necessary, merging changes by the same author during the same day.
 
Changelogs are small YAML files that developers create to add their pull requests' changes to the master changelog.html file.  A python script run by a maintainer collects all the changes specified and generates the HTML necessary, merging changes by the same author during the same day.
  
On the /tg/station Github changelogs can be automatically generated from special formatting in the body of a PR's description.
+
=== Online auto-creation ===
 +
On the /tg/station GitHub, a formatted block in your PR's description as described above will cause a bot to automatically generate a <tt>.yml</tt> file.
  
 
The idea is to reduce merge conflicts caused by two PRs trying to edit the same file.
 
The idea is to reduce merge conflicts caused by two PRs trying to edit the same file.
 
== Creating a Changelog ==
 
  
 
=== Committing a .yml file ===
 
=== Committing a .yml file ===
Line 25: Line 58:
  
 
'''File content example:'''
 
'''File content example:'''
    author: Deantwo
+
author: Deantwo
   
+
    delete-after: True
+
delete-after: True
   
+
    changes:  
+
changes:
      - rscadd: "Added laser rifles for everyone."
+
  - rscadd: "Added laser rifles for everyone."
      - rscdel: "Removed everyone's brains."
+
  - rscdel: "Removed everyone's brains."
 
 
=== Online auto-creation ===
 
By formatting text in the body of your PR description you can have a changelog .yml file automatically generated for you.
 
Declare the start of a changelog entry with :cl: and close it with /:cl:; anything in between these two tags will included, remember to use prefixes for each line. See below for a list of valid prefixes.
 
An author can be set after the :cl: tag, if omitted your Github username will be used by default.
 
Don't use double quotation marks " " in your entry as they are used as delimiters by the changelog system which will break upon encountering them.
 
 
 
'''Format example:'''
 
    :cl: Deantwo
 
    rscadd: Added laser rifles for everyone.
 
    rscdel: Removed everyone's brains.
 
    /:cl:
 
  
 
=== Updating the Changelog ===
 
=== Updating the Changelog ===
  
:''Only maintainers need to do this.''
+
''Only maintainers need to do this.''
  
* First, install python 2.7, pip, and PyYaml:
+
* First, install python3, pip, and PyYaml:
 
** After installing python and ensuring it and its Scripts/ folder is in PATH, download and run [https://raw.githubusercontent.com/pypa/pip/master/contrib/get-pip.py get-pip.py] with python.
 
** After installing python and ensuring it and its Scripts/ folder is in PATH, download and run [https://raw.githubusercontent.com/pypa/pip/master/contrib/get-pip.py get-pip.py] with python.
 
** Once pip is installed run the following commands in your terminal
 
** Once pip is installed run the following commands in your terminal
Line 57: Line 78:
 
* On Linux or other codebases, run <code>python tools/ss13_genchangelog.py html/changelog.html html/changelogs</code>
 
* On Linux or other codebases, run <code>python tools/ss13_genchangelog.py html/changelog.html html/changelogs</code>
  
== Screwed up Changelog ==
+
=== Screwed up Changelog ===
 
If a changelog needs to be edited after merge, a maintainer will need to edit the html/changelogs/.all_changelog.yml file in order to fix the database. (This file is hidden on Linux and Mac OSX.)
 
If a changelog needs to be edited after merge, a maintainer will need to edit the html/changelogs/.all_changelog.yml file in order to fix the database. (This file is hidden on Linux and Mac OSX.)
  
== Valid Prefixes ==
 
Any of these prefixes can be used when creating a changelog.
 
*[[File:Bug-minus.png]] bugfix
 
*[[File:Hard-hat-exclamation.png]] wip
 
*[[File:Wrench-screwdriver.png]] tweak
 
*[[File:Music-plus.png]] soundadd
 
*[[File:Music-minus.png]] sounddel
 
*[[File:Tick-circle.png]] rscadd
 
*[[File:Cross-circle.png]] rscdel
 
*[[File:Image-plus.png]] imageadd
 
*[[File:Image-minus.png]] imagedel
 
*[[File:Spell-check.png]] spellcheck
 
*[[File:Burn-exclamation.png]] experiment
 
  
 
{{Contribution guides}}
 
{{Contribution guides}}
[[Category:Guides]] [[Category:Game Resources]]
 

Latest revision as of 03:40, 4 December 2020

Guide to contributing to the game

You can add changelog entries by using the following template in the body of your pull request:

:cl:
prefix: text
prefix: text
prefix: text
/:cl:

Your GitHub username is credited by default, or you can add a name at the end of the :cl: line to override it.

Valid prefixes are:

  • Tick-circle.png add
  • Cross-circle.png del
  • Bug-minus.png fix
  • Hard-hat-exclamation.png wip
  • Wrench-screwdriver.png tweak
  • Burn-exclamation.png experiment
  • Spell-check.png spellcheck
  • Music-plus.png soundadd
  • Music-minus.png sounddel
  • Image-plus.png imageadd
  • Image-minus.png imagedel
  • Scales icon.png balance
  • Coding.png code
  • Burn-exclamation.png refactor
  • Chrome-wrench.gif config
  • Ban.png admin
  • Hard-hat-exclamation.png server


Advanced information

Note: This guide thanks to friends from /vg/.

Changelogs are small YAML files that developers create to add their pull requests' changes to the master changelog.html file. A python script run by a maintainer collects all the changes specified and generates the HTML necessary, merging changes by the same author during the same day.

Online auto-creation

On the /tg/station GitHub, a formatted block in your PR's description as described above will cause a bot to automatically generate a .yml file.

The idea is to reduce merge conflicts caused by two PRs trying to edit the same file.

Committing a .yml file

PR changelogs are temporary and just get deleted after they're merged into the master changelog.

  1. Create html/changelogs/USERNAME-BRANCHNAME.yml.
    1. Go to /master/html/changelogs/ on your branch.
    2. Create file USERNAME-BRANCHNAME.yml in the folder, where 'BRANCHNAME' the name of the branch on your fork and 'USERNAME' is your github username.
      • Example: Deantwo-BrainlessShooting.yml
      • File name is not super important but helps the maintainers know who made the file and which PR it is related to. Also prevents conflicts since two files won't have the same name.
  2. Copy the contents of this.
  3. Fill it out.
    • Make sure to set delete-after to true.
    • Also ensure you update the author name so you get credited appropriately.
  4. PROOFREAD. Changelog entries are final after they're merged.
  5. Add it to git so it's included with your PR.

File content example:

author: Deantwo

delete-after: True

changes:
  - rscadd: "Added laser rifles for everyone."
  - rscdel: "Removed everyone's brains."

Updating the Changelog

Only maintainers need to do this.

  • First, install python3, pip, and PyYaml:
    • After installing python and ensuring it and its Scripts/ folder is in PATH, download and run get-pip.py with python.
    • Once pip is installed run the following commands in your terminal
    • pip install PyYaml
    • pip install beautifulsoup4
  • With /tg/station's code, simply run makeChangelog.bat.
  • On Linux or other codebases, run python tools/ss13_genchangelog.py html/changelog.html html/changelogs

Screwed up Changelog

If a changelog needs to be edited after merge, a maintainer will need to edit the html/changelogs/.all_changelog.yml file in order to fix the database. (This file is hidden on Linux and Mac OSX.)


Hosting Hosting a serverSetting up the databaseWorking with /tg/station as an upstream repository
Contributing Guide to contributing to the gameSetting up gitDownloading the source codeReporting issuesChangelogs
Coding Understanding SS13 codeSS13 for experienced programmersCode docsCoding standardsGetting Your Pull AcceptedBinary flags‎Text FormattingMySQL
Mapping Guide to mappingMap mergerGuide to door access
Spriting Guide to spritingResolving icon conflicts
Wiki Guide to contributing to the wikiWikicodeAutowiki