Difference between revisions of "Guide to Changelogs"

From NSV13
Jump to navigationJump to search
imported>Paprika
m (make link NSV)
 
(6 intermediate revisions by 5 users not shown)
Line 2: Line 2:
  
 
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.
  
 
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.
Line 7: Line 9:
 
== Creating a Changelog ==  
 
== Creating a Changelog ==  
  
−
=== Pull Requests ===
+
=== 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.
 +
 
 +
'''Format example:'''
 +
    :cl: Deantwo
 +
    rscadd: Added laser rifles for everyone.
 +
    rscdel: Removed everyone's brains.
 +
    /:cl:
 +
 
 +
=== Committing a .yml file ===
 
PR changelogs are temporary and just get deleted after they're merged into the master changelog.
 
PR changelogs are temporary and just get deleted after they're merged into the master changelog.
  
 
# Create <code>html/changelogs/''USERNAME-BRANCHNAME''.yml</code>.
 
# Create <code>html/changelogs/''USERNAME-BRANCHNAME''.yml</code>.
 
## Go to <code>/master/html/changelogs/</code> on your branch.
 
## Go to <code>/master/html/changelogs/</code> on your branch.
−
## Create file <code>''USERNAME-BRANCHNAME''.yml</code> in the folder, where 'BRANCHNAME' the name of the branch.
+
## Create file <code>''USERNAME-BRANCHNAME''.yml</code> in the folder, where 'BRANCHNAME' the name of the branch on your fork and 'USERNAME' is your github username.
−
##* Example: <code>Deantwo-ChemMasterGetsGloomy.yml</code>
+
##* Example: <code>Deantwo-BrainlessShooting.yml</code>
 
##* 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.
 
##* 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.
−
# Copy the contents of [https://github.com/tgstation/-tg-station/blob/master/html/changelogs/example.yml this].
+
# Copy the contents of [https://github.com/beestation/NSV13/blob/master/html/changelogs/example.yml this].
 
# Fill it out.
 
# Fill it out.
 
#* Make sure to set delete-after to true.
 
#* Make sure to set delete-after to true.
Line 28: Line 41:
 
      
 
      
 
     changes:  
 
     changes:  
−
       - rscadd: "Added grenades for everyone."
+
       - rscadd: "Added laser rifles for everyone."
 
       - rscdel: "Removed everyone's brains."
 
       - rscdel: "Removed everyone's brains."
−
 
−
=== Maintainer Changelogs ===
 
−
Maintainers can have their own changelogs.  Follow the same directions as above, but use USERNAME.yml and leave delete-after false.
 
  
 
=== Updating the Changelog ===
 
=== Updating the Changelog ===
Line 38: Line 48:
 
:''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 48: Line 58:
 
== 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]]
 
[[Category:Guides]] [[Category:Game Resources]]

Latest revision as of 04:22, 11 March 2021

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.

On the /tg/station Github changelogs can be automatically generated from special formatting in the body of a PR's description.

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

Creating a Changelog[edit | edit source]

Online auto-creation[edit | edit source]

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.

Format example: 

   :cl: Deantwo
   rscadd: Added laser rifles for everyone.
   rscdel: Removed everyone's brains.
   /:cl:

Committing a .yml file[edit | edit source]

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[edit | edit source]

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[edit | edit source]

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[edit | edit source]

Any of these prefixes can be used when creating a changelog.

  • Bug-minus.png bugfix
  • Hard-hat-exclamation.png wip
  • Wrench-screwdriver.png tweak
  • Music-plus.png soundadd
  • Music-minus.png sounddel
  • Tick-circle.png rscadd
  • Cross-circle.png rscdel
  • Image-plus.png imageadd
  • Image-minus.png imagedel
  • Spell-check.png spellcheck
  • Burn-exclamation.png experiment
Contribution guides
General Hosting a server, Setting up git, Guide to working with tgstation as an upstream repository, Downloading the source code, Guide to contributing to the game, Reporting issues, Game resources category, Guide to changelogs
Database (MySQL) Setting up the database, MySQL
Coding Coding standards, Understanding SS13 code, SS13 for experienced programmers, Binary flags‎, Getting Your Pull Accepted, Text Formatting
Mapping Guide to mapping, Map merger
Spriting Guide to spriting
Wiki Guide to contributing to the wiki, Wikicode, Maintainer Assignments
Retrieved from "https://nsv.beestation13.com/mediawiki2/index.php?title=Guide_to_Changelogs&oldid=32474"