Extending Lorekeeper - Revision history

Mercury at 17:13, 21 November 2021

2021-11-21T17:13:43Z

Mercury at 18:21, 1 November 2021

2021-11-01T18:21:58Z

Mercury: /* 2.0.0 */

2021-10-24T15:44:56Z

2.0.0

Mercury: /* Updating Extensions with Lorekeeper */

2021-06-04T16:28:16Z

Updating Extensions with Lorekeeper

Mercury at 16:01, 4 June 2021

2021-06-04T16:01:12Z

Mercury at 15:52, 4 June 2021

2021-06-04T15:52:28Z

Mercury at 15:46, 4 June 2021

2021-06-04T15:46:37Z

Mercury at 15:27, 4 June 2021

2021-06-04T15:27:24Z

Mercury at 15:23, 4 June 2021

2021-06-04T15:23:52Z

Mercury at 17:16, 2 June 2021

2021-06-02T17:16:50Z

@@ Line 50: / Line 50: @@
 *If a release branch exists, it is recommended that you build upon it.
 **This is practical both because release branches are inherently stable-- only receiving bugfixes-- and because when the release they represent becomes the current version, extensions built upon it will already be up-to-date or close to it.
-*Otherwise, it is recommended to use the current release (on <u>master</u>).
+*Otherwise, it is recommended to use the current release (on <u>main</u>).
 While it is not unviable to build on <u>develop</u>, it's not recommended as it incentivizes users toward a fundamentally unstable branch. Using <u>develop</u>, especially for a live site, is only advisable if you know what you're doing-- which users only interested in a given extension's functionality may or may not be well-equipped to handle, putting extra stress on volunteer support.
@@ Line 99: / Line 99: @@
 *The name of the extension
 *Some note that it is being released
-*A note of what branch the extension is built on (assuming it is not <u>master</u>)
+*A note of what branch the extension is built on (assuming it is not <u>main</u>)
 *A short description of the extension's function
 *A link to the documentation page created in the previous step

@@ Line 75: / Line 75: @@
 ====Creating a Documentation Page====
-If you have not already, you will need to register for an account on this wiki and request editing permissions via the technical-support channel in the [https://discord.gg/U4JZfsu Lorekeeper Discord server] or via issue on the GitHub repo. When ready, you can create a documentation page for your extension via this process:
+If you have not already, you will need to register for an account on this wiki and request editing permissions via the staff-support channel in the [https://discord.gg/U4JZfsu Lorekeeper Discord server] or via issue on the GitHub repo. When ready, you can create a documentation page for your extension via this process:
 #Enter the name of your extension (the wiki key you specified in the extension_tracker config file, minus any underscores), prefixed by <code>Extensions:</code>, into the search bar. (i.e. Extensions:Separate Prompts)

← Older revision		Revision as of 15:44, 24 October 2021
Line 144:		Line 144:

	The second is that extensions which were not developed with <u>modified-main</u> or its component extensions in mind may encounter conflicting changes, especially as a consequence of the changes included [[Extensions:Stacked Inventories\|Stacked Inventories]], that require reworking part of the extension being updated's methods.		The second is that extensions which were not developed with <u>modified-main</u> or its component extensions in mind may encounter conflicting changes, especially as a consequence of the changes included [[Extensions:Stacked Inventories\|Stacked Inventories]], that require reworking part of the extension being updated's methods.
		+
		+	It's also '''highly recommended''' to update extensions to include extension tracker information in config/lorekeeper/extension_tracker.php!
	[[Category:Documentation]]		[[Category:Documentation]]

@@ Line 112: / Line 112: @@
 You may find it useful to browse the channel and see how others have formatted this information before constructing your release announcement.
-==== Announcing updates ====
+====Announcing updates====
 When you update an extension, if necessary, update the documentation as present on the wiki first. Then, announce the changes in the Discord server's extension releases and updates channel. An update notice should contain the following:
-* The name of the extension
+*The name of the extension
-* Some note that it is being updated
+*Some note that it is being updated
-* A summary of the changes
+*A summary of the changes
-* Any commands that must be run as a consequence of the updates
+*Any commands that must be run as a consequence of the updates
 It may also include:
-* A link to the wiki documentation page
+*A link to the wiki documentation page
-* A link to the extension's branch on GitHub
+*A link to the extension's branch on GitHub
-* Where the updates have been tested
+*Where the updates have been tested
-* Any other relevant information
+*Any other relevant information
+*
@@ Line 141: / Line 141: @@
 *<code>Arr::only()</code> is now used instead of <code>array_only()</code>
 *<code>getRawOriginal()</code> now serves the purpose <code>getOriginal()</code> previously served (see for example the loot table display name field)
 The second is that extensions which were not developed with <u>modified-main</u> or its component extensions in mind may encounter conflicting changes, especially as a consequence of the changes included [[Extensions:Stacked Inventories|Stacked Inventories]], that require reworking part of the extension being updated's methods.
 [[Category:Documentation]]

@@ Line 94: / Line 94: @@
 It may be useful to you in filling out the page to make use of [[Template:Github]], particularly if your extension makes use of an additional package. The template's page outlines the particulars of its use as well as parameters.
-==== Announcing the Release ====
+====Announcing the Release====
 The [https://discord.gg/U4JZfsu Lorekeeper Discord server] has a dedicated channel for announcing extension releases and updates, <code>#ext-releases-updates</code>. A release message should contain the following:
 * The name of the extension
-* Some note that it is being released
+* Some note that it is being updated
-* A note of what branch the extension is built on (assuming it is not <u>master</u>)
+* A summary of the changes
-* A short description of the extension's function
+* Any commands that must be run as a consequence of the updates
-It may also contain:
+It may also include:
 * A link to the extension's branch on GitHub
-* Install instructions (these '''must''' be on the wiki documentation page, but may be included here as well)
+* Where the updates have been tested
+* Any other relevant information
+*

@@ Line 70: / Line 70: @@
 When you have made modifications as desired and tested them to the best of your ability, you may wish to release these modifications to the public. This is a three-part process:
-* Ensure all changes have been committed to your extension branch, and push it to your fork on GitHub
+*Ensure all changes have been committed to your extension branch, and push it to your fork on GitHub
-* Create documentation for it on this wiki
+*Create documentation for it on this wiki
-* Announce the release in the Lorekeeper discord server
+*Announce the release in the [https://discord.gg/U4JZfsu Lorekeeper Discord server]
-==== Creating a Documentation Page ====
+====Creating a Documentation Page====
-If you have not already, you will need to register for an account on this wiki and request editing permissions via the technical-support channel in the [https://discord.gg/U4JZfsu Lorekeeper discord server] or via issue on the GitHub repo. When ready, you can create a documentation page for your extension via this process:
+If you have not already, you will need to register for an account on this wiki and request editing permissions via the technical-support channel in the [https://discord.gg/U4JZfsu Lorekeeper Discord server] or via issue on the GitHub repo. When ready, you can create a documentation page for your extension via this process:
-# Enter the name of your extension (the wiki key you specified in the extension_tracker config file, minus any underscores), prefixed by <code>Extensions:</code>, into the search bar. (i.e. Extensions:Separate Prompts)
+#Enter the name of your extension (the wiki key you specified in the extension_tracker config file, minus any underscores), prefixed by <code>Extensions:</code>, into the search bar. (i.e. Extensions:Separate Prompts)
-#* This will bring you to a search results page informing you that there are no results, as the page does not yet exist.
+#*This will bring you to a search results page informing you that there are no results, as the page does not yet exist.
-# The title you entered will be present as a red link; click this to be brought to page creation.
+#The title you entered will be present as a red link; click this to be brought to page creation.
-# The page will then preload with the following: <code><nowiki>{{subst:Extension Page}}</nowiki></code>
+#The page will then preload with the following: <code><nowiki>{{subst:Extension Page}}</nowiki></code>
-## This will apply the [[Template:Extension Page|Extension Page template]] once the page is saved.
+##This will apply the [[Template:Extension Page|Extension Page template]] once the page is saved.
-# To save the page, enter and delete a space or something to that effect, then click "Save changes..." at the top right.
+#To save the page, enter and delete a space or something to that effect, then click "Save changes..." at the top right.
 The page will then be created with the full extension page template. You may now fill out the page like so:
-# Click "Edit source" in the top right of the page, which will bring you to the editing dialogue
+#Click "Edit source" in the top right of the page, which will bring you to the editing dialogue
-# Fill out the infobox, which contains basic information about the extension
+#Fill out the infobox, which contains basic information about the extension
-#* Information about the template can be found at [[Template:Extensioninfobox]]. Brief explanations of each parameter are also included in the page template.
+#*Information about the template can be found at [[Template:Extensioninfobox]]. Brief explanations of each parameter are also included in the page template.
-# Fill each section of the page body out as appropriate.
+#Fill each section of the page body out as appropriate.
-#* Most of the body of the page should be self-explanatory; comments are also provided as prompts for each section.
+#*Most of the body of the page should be self-explanatory; comments are also provided as prompts for each section.
 It may be useful to you in filling out the page to make use of [[Template:Github]], particularly if your extension makes use of an additional package. The template's page outlines the particulars of its use as well as parameters.
+*

@@ Line 54: / Line 54: @@
 While it is not unviable to build on <u>develop</u>, it's not recommended as it incentivizes users toward a fundamentally unstable branch. Using <u>develop</u>, especially for a live site, is only advisable if you know what you're doing-- which users only interested in a given extension's functionality may or may not be well-equipped to handle, putting extra stress on volunteer support.
-Once you have identified the branch you're going to build upon, check it out/switch to it, depending. It is now time to make the branch in which you will build your extension. You will want to select a succinct, descriptive name, preferably no more than three or four words, which summarizes the purpose of your extension. You should separate the words in the branch name using dashes <code>-</code> or underscores <code>_</code>.
+Once you have identified the branch you're going to build upon, check it out/switch to it, depending. It is now time to make the branch in which you will build your extension. You will want to select a succinct, descriptive name, preferably no more than three or four words, which summarizes the purpose of your extension. You should separate the words in the branch name using dashes <code>-</code> or underscores <code>_</code>. You must also browse the [[:Category:Extensions|Extensions Category]] and ensure that this name is unique.
 *It is '''strongly recommended''' that you use the <code>extension/</code> prefix for extension branches for clarity.
-*'''<u>Do not</u>''' prefix extension branches with  <code>feature/</code>, as feature branches are intended specifically for merging into core Lorekeeper.
+*'''<u>Do not</u>''' prefix extension branches with <code>feature/</code>, as feature branches are intended specifically for merging into core Lorekeeper.
-**Encouraging users to pull branches with the <code>feature/</code> prefix in this way creates conflicting messages, as regular users should '''never''' pull any of these branches due to the risk of unfinished and/or unreviewed code.
+**Encouraging users to pull branches with the <code>feature/</code> prefix in this way creates conflicting messages and risk of difficulty for regular users, as they should '''never''' pull any of these branches due to the risk of unfinished and/or unreviewed code.
 **See [[Contributing to Lorekeeper]] for more information.
@@ Line 64: / Line 64: @@
 Note that if your planned extension includes user notifications, you should familiarize yourself with the [[Community Notification Standard]] and request a notification block if necessary.
 ===Releasing the Extension===
+*

@@ Line 74: / Line 74: @@
 However, releases may contain certain points of concern or known breaking changes from the previous release. These are noted here in brief.
-=== 2.0.0 ===
+===2.0.0===
 There are two major factors involved in updating extensions to 2.0.0. The first is that the Laravel version Lorekeeper uses has been upgraded from 5.8 to 8; consequently, some methods have changed.
-* <code>Arr::only([])</code> is now used instead of <code>array_only([])</code>
+*<code>Arr::only()</code> is now used instead of <code>array_only()</code>
-* <code>getRawOriginal()</code> now serves the purpose <code>getOriginal()</code> previously served (see for example the loot table display name field)
+*<code>getRawOriginal()</code> now serves the purpose <code>getOriginal()</code> previously served (see for example the loot table display name field)
-The second is that extensions which were not developed with
+The second is that extensions which were not developed with <u>modified-main</u> or its component extensions in mind may encounter conflicting changes, especially as a consequence of the changes included [[Extensions:Stacked Inventories|Stacked Inventories]], that require reworking part of the extension being updated's methods.
 [[Category:Documentation]]

← Older revision		Revision as of 15:23, 4 June 2021
Line 70:		Line 70:

	==Updating Extensions with Lorekeeper==		==Updating Extensions with Lorekeeper==
		+	In most cases, Lorekeeper updates will not break extension functionality. However, conflicts may ensue; for this reason, it is recommended to update extensions at minimum to each current release. When updating, make an effort to preserve incoming changes from Lorekeeper updates alongside the changes from your extension.
		+
		+	However, releases may contain certain points of concern or known breaking changes from the previous release. These are noted here in brief.
		+
		+	=== 2.0.0 ===
		+	There are two major factors involved in updating extensions to 2.0.0. The first is that the Laravel version Lorekeeper uses has been upgraded from 5.8 to 8; consequently, some methods have changed.
		+
		+	* <code>Arr::only([])</code> is now used instead of <code>array_only([])</code>
		+	* <code>getRawOriginal()</code> now serves the purpose <code>getOriginal()</code> previously served (see for example the loot table display name field)
		+
		+	The second is that extensions which were not developed with
	[[Category:Documentation]]		[[Category:Documentation]]

@@ Line 56: / Line 56: @@
 Once you have identified the branch you're going to build upon, check it out/switch to it, depending. It is now time to make the branch in which you will build your extension. You will want to select a succinct, descriptive name, preferably no more than three or four words, which summarizes the purpose of your extension. You should separate the words in the branch name using dashes <code>-</code> or underscores <code>_</code>.
-* It is '''strongly recommended''' that you use the <code>extension/</code> prefix for extension branches for clarity.
+*It is '''strongly recommended''' that you use the <code>extension/</code> prefix for extension branches for clarity.
-* '''<u>Do not</u>''' prefix extension branches with  <code>feature/</code>, as feature branches are intended specifically for merging into core Lorekeeper.
+*'''<u>Do not</u>''' prefix extension branches with  <code>feature/</code>, as feature branches are intended specifically for merging into core Lorekeeper.
-** Encouraging users to pull branches with the <code>feature/</code> prefix in this way creates conflicting messages, as regular users should '''never''' pull any of these branches due to the risk of unfinished and/or unreviewed code.
+**Encouraging users to pull branches with the <code>feature/</code> prefix in this way creates conflicting messages, as regular users should '''never''' pull any of these branches due to the risk of unfinished and/or unreviewed code.
-** See [[Contributing to Lorekeeper]] for more information.
+**See [[Contributing to Lorekeeper]] for more information.
 Once you've created your branch, make changes as appropriate.
@@ Line 65: / Line 65: @@
 Note that if your planned extension includes user notifications, you should familiarize yourself with the [[Community Notification Standard]] and request a notification block if necessary.
-=== Releasing an Extension ===
+===Releasing the Extension===
+*