diff --git a/src/main/resources/docs/Changelog b/src/main/resources/docs/Changelog index 3eb6b6b27..aaf42696d 100644 --- a/src/main/resources/docs/Changelog +++ b/src/main/resources/docs/Changelog @@ -1,3 +1,116 @@ +==3.3.5== + +CommandHelper 3.3.5 supports Minecraft 1.16.5 - 26.1 + +The largest features of this release are that it now uses and requires Java 16 and that the support range for Minecraft +versions was changed. Additionally, various backend changes have been committed, which improve the reliability and +performance of the system, and allow for additional planned changes in the future, particularly around static analysis, +user objects, and other language features. + +=== Overview === + +* Added support for 1.17 - 26.1 Minecraft entity data, item meta, enums, and other functionality. +* MethodScript source is now hardened against bidi attacks. https://trojansource.codes/trojan-source.pdf +* Various improvements to the LangServ, which increases the functionality of the Visual Studio Code IDE. \ +Things such as code outline and integration with proc docs is now supported. The idea of a "workspace" was added, \ +which allows for all code to be handled as a whole project, rather than a bunch of individual files. For instance, \ +the ability to go to a proc declaration from a reference was added, and smart comments added to a proc now show \ +up when hovering over a proc reference. Requires static analysis to be enabled. +* RCON support was added +* Declarative event prefilters were added. This has little visible effect to end users, other than that prefilters \ +should be more performant now, and additional error checking can be done to ensure correct prefilter usage, including \ +incorrect values, and unexpected additional (and unused) values. The framework is added now, and more events will \ +be onboarded onto the system in the future. Some of the changes require Static Analysis to be enabled (disabled by +default). +* Initial framework support is added for function signatures. This allows native functions to specify return types and \ +expected parameters, which allows for better compile time error detection, if static analysis is turned on. For now, \ +most of the functions are not onboarded yet, and anyways, typechecking is disabled by default, but this will be \ +enabled in the near future. If you wish to go ahead and try out your code under typechecking, please enable it \ +in the static-analysis-config.ini file in the prefs folder. This will be enabled by default in the VSCode IDE plugin \ +in the next version, and once deemed stable, will be enabled by default, and eventually be unable to be turned off \ +in normal circumstances. +* CommandHelper reloading (that is, on startup, and also with the /recompile command) has been substantially altered. \ +Now, compilation and execution are fully separated into two distinct steps, which means that code changes that cause \ +a compile error will not stop the old, previously working code from running. Only successful recompiles will allow \ +for the new code to begin to be executed. Preferences (files in prefs/) are now reloaded as part of a recompile. \ +The halt-on-failure preference now shuts down the server if, on initial startup, the code will not compile, or other \ +configuration is wrong, such that the code can not come up completely. This is useful if, for instance, some server \ +security is provided through CommandHelper, so that if something changes and the code no longer will run, it is better \ +for the server to shut down than run unprotected. Various other backend improvements were made in this area. +* Extension load time was reduced. +* return can now be used as a keyword, such as return expression(); or return; +* continue and break can also be used as keywords, in the same way. +* Full support for statements has been added. In either strict and non-strict mode, adding a semicolon creates a \ +statement. For now, they are not required in any mode, though they will cause errors in strict mode if they are \ +used in places they shouldn't. To keep backwards compatibility, in non-strict mode, when a statement is used where \ +it shouldn't be, the value will be "pulled up" and not cause any errors. For instance, for the code \ +if(@a;){}, this will cause an error in strict mode, but work like if(@a){} in non-strict \ +mode. Eventually, this will cause a warning in non-strict mode, but additional work is needed before that can be \ +implemented. In both modes, when statements are used, properly, this may increase runtime performance, because it \ +skips the automatic sconcat feature, which is required for small aliases, but is inefficient in all other cases. +* First class proc references are added. Assuming a proc named _test is defined, proc _test will return \ +a reference to it, which can be stored in a variable, or otherwise passed around as an argument. +* Closures, iclosures, and proc references now extend the new Callable interface. +* All callables can be executed with parenthetical notation, no matter how they are stored. Previously this \ +only worked with top level variables, such as @c() but now it works with any other format, including \ +direct returns from other functions and array references, for instance, assuming func returns a Callable, \ +func()() will execute it. +* Tab completion is now enhanced for aliases defined with the @command syntax, if they also provide type information \ +in @param tags. For instance, if the alias is /test $enum and @param $enum WorldEnvironment \ +is provided, then the $enum value will automatically provide autocomplete with the values from the WorldEnvironment enum. +* Support for variadic arguments is added. Callables may now be defined with a variadic type in the last parameter, \ +which will match all overflow parameters, for instance proc _test(string... @values) can now be called \ +such as _test('a', 'b', 'c'), and @values will be an array of strings array('a', 'b', 'c') \ +within the proc. +* Additional methods of handling dynamic includes and static analysis have been added. Forward proc declarations, \ +@{DynamicProc} annotations, and additional file options. See the page on [[Procedures]] for more details. +* Annotations have been added. For now, only @{DynamicProc} exists, though this will be expanded on in the future. +* Very early support for LLVM is being introduced. This is not generally usable for basically anything yet, but you \ +are encouraged to take a look and provide feedback if you are a command line user. +* Added soft casting (checking / non-converting) using parentheses. +* As always, hundreds of additional performance fixes and bug fixes and other minor things. + +=== Function API Removals === + +These deprecated functions have been removed: spawn_mob (use spawn_entity), tame_mob (use set_mob_owner), +enchant_inv (use enchant_item), enchant_rm_inv (use remove_item_enchant), get_enchant_inv (use get_item_enchants), +can_enchant_target (use can_enchant_item), get_block_at (use get_block), set_block_at (use set_block) + +=== Function API Additions === + +MethodScript additions: {{function|array_fill}}, {{function|fixed_array}}, {{function|equals_epsilon}}, +{{function|array_clear}}, {{function|easing}}, {{function|ease_between_loc}}, {{function|x_get_lock}}, +{{function|string_compare}}, {{function|string_compare_ic}}, {{function|matrix_add}}, {{function|matrix_can_add}}, +{{function|matrix_can_multiply}}, {{function|matrix_clone}}, {{function|matrix_create}}, +{{function|matrix_determinant}}, {{function|matrix_equals}}, {{function|matrix_format}}, {{function|matrix_get_column}}, +{{function|matrix_identity}}, {{function|matrix_is_square}}, {{function|matrix_multiply}}, {{function|matrix_norm}}, +{{function|matrix_scalar_multiply}}, {{function|matrix_submatrix}}, {{function|matrix_subtract}}, +{{function|matrix_to_array}}, {{function|matrix_trace}}, {{function|matrix_transpose}} + +Minecraft additions: {{function|get_banner_patterns}}, {{function|get_entity_freezing}}, +{{function|get_hanging_direction}}, {{function|get_world_autosave}}, {{function|is_sign_text_glowing}}, +{{function|psend_block_damage}}, {{function|set_banner_patterns}}, {{function|set_entity_freezing}}, +{{function|set_hanging_direction}}, {{function|set_sign_text_glowing}}, {{function|set_world_autosave}}, +{{function|bone_meal_block}}, {{function|has_inventory}}, {{function|pborder}}, {{function|set_pborder}}, +{{function|get_mob_love_ticks}}, {{function|set_mob_love_ticks}}, {{function|plocale}}, {{function|is_sign_waxed}}, +{{function|set_sign_waxed}}, {{function|get_decorated_pot_sherds}}, {{function|set_decorated_pot_sherds}}, +{{function|select_entities}}, {{function|get_display_entity}}, {{function|set_display_entity}}, +{{function|phas_recipe}}, {{function|pgive_recipe}}, {{function|get_force_loaded_chunks}}, +{{function|set_chunk_force_loaded}}, {{function|set_end_gateway_exit}}, {{function|set_end_gateway_age}}, +{{function|pforce_respawn}}, {{function|get_scoreboard_entries}}, {{function|phide_entity}}, {{function|pshow_entity}}, +{{function|pcan_see_entity}}, {{function|get_entity_transient_id}}, {{function|entity_in_water}}, +{{function|stop_sound_category}}, {{function|get_transformation_from_matrix}}, {{function|set_entity_rotation}}, +{{function|psend_equipment}}, {{function|get_player_ping}},{{function|has_scoreboard_tag}}, +{{function|get_player_input}}, {{function|get_entity_saves_on_unload}}, {{function|set_entity_saves_on_unload}}, +{{function|action_msg}}, {{function|is_player_sleeping_ignored}}, {{function|set_player_sleeping_ignored}}, +{{function|get_entity_killer}}, {{function|set_entity_killer}}, {{function|is_entity_hidden_by_default}}, +{{function|set_entity_hidden_by_default}}, {{function|get_entity_pose}}, {{function|set_entity_pose}} + +=== Event API Additions === + +item_pre_anvil, item_pre_smithing, item_pre_grindstone, player_bucket_fill, player_bucket_empty, +player_advancement_done, player_stop_using_item, entity_toggle_swim + ==3.3.4== CommandHelper 3.3.4 supports Minecraft 1.13.2 - 1.16.5. All extensions must be updated when upgrading from previous versions. diff --git a/src/main/resources/docs/VersionBumpGuide b/src/main/resources/docs/VersionBumpGuide new file mode 100644 index 000000000..5950877e1 --- /dev/null +++ b/src/main/resources/docs/VersionBumpGuide @@ -0,0 +1,51 @@ + +This is a guide for developers when doing a version bump of MethodScript. + +== General Procedure == + +The general procedure for development is to develop on the "current version", say version 2.0.0, and then release it as +version 2.0.0-final. This is slightly different than many systems, where "version 2.0.0" is the release version, and +dev builds are "2.0.0-SNAPSHOT", but for infrequently released projects, this seems to be a better approach. + +As of version 3.3.4, the release tags have been standardized on ''commandhelper--final''. + +== Step 1: Prepare for new version == + +This is the largest step in the process. The [[Changelog]] page must first be updated with the highlights of the +previous development cycle. This can be somewhat easily determined by reading through the git log, though this will +generally only reveal major points, which is fine. These bullet points go in under the new feature overview. + +The command to read the relevant git logs is <%PRE|git log ..HEAD --reverse%>. This will provide them +in chronological order, starting from the first commit after the tag. Read through all of them, extract the highlights, +and fill out the bullet points. + +Next, we need to gather a list of new functions and events and other elements. +This can be done in MethodScript with this code snippet: + +<%CODE|@version = ''; @api = json_decode(shell(array('mscript', '--', 'json-api'))); foreach(@top: @data in @api) { if(@top == 'extensions') { continue(); }; msg(@top); foreach(@n: @e in @data) { if(@e['since'] == @version) { msg(' ' . @n); } } }; die();%> + +Additionally, make any final changes to the documentation that you wish to be under the current version, as it will only +upload under the site on that version one last time. + +Commit all these changes, and push them out. + +== Step 2: Do a version bump == + +This is the step that actually bumps up the version. + +<%PRE|mvn clean release:clean release:prepare%> + +Follow the prompts, then git push when complete. + +== Step 3: Pin the build (requires Azure Portal access) == + +After the build for this final commit is complete, download the jar. Login to the Azure portal (portal.azure.com) and +access the methodscriptbuilds storage account blade. Access the Storage Browser, Blob Containers, and +commandhelperpinned container. Add directory (following the format of the others) then upload the jar, naming it +commandhelper--final.jar. + +== Step 4: Create new version == + +Open the pom file, and change the version there to the new version. Go to MSVersion and add a new enum (the LATEST value +is determined automatically). Make a commit and push. On this build, AggressiveDeprecations might start kicking in +immediately, so ensure you're aware of what might change there.