#Set up processes to improve NH's core libs/APIs quality

38 messages · Page 1 of 1 (latest)

dusk ember
#

We have a good chunk of technical debt in NH and while we are working on catching it up, we need to improve and harmonize code quality of core libs used in NH.

We should decouple actual pack dev from the development of tools to improve pack dev. As such, this thread is here mainly to debate on what we should do while we want to do big refactors or develop new tools. This does not concern the regular pack dev as for that, the usual quality checks such as PR reviews are enough in my opinion. The benefits of having such things for core components of NH is that for those less familiar with good coding practices, being constantly exposed to them will slowly improve the average code quality of the rest of the NH codebase.

I am in no way a professional dev so i don't know the good practices in this field, but from my experience as a network & telecom engineer, we need 2 things:

  • a thing explaining the historical big changes on the project
  • a place to explain how things work precisely to convey the intentions behind the architecture of the code, so users will be able to figure out how to properly use what has been developped.

Apparently javadoc is what is the easiest to work with, but you guys are entirely free to design whatever you think could achieve that two points I listed above.

chilly thorn
#

honestly there two options for the first bullet point one i can see is a more advance implementation of patch notes or do comments or use something called redmine or git-flow

sick bloom
#

I think "Historical big changes" are only of interest insofar as they can serve as context for explaining the current state of the project, as such I really see them as an extension to the need to explain our existing systems.

The kind of JavaDoc we need is like that you can find for Collection in Java's Collection Framework: https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/Collection.html

It neatly sits at the core of the system it's named after and concisely explains the main concepts that underpin the system, while providing links to documentation for it's main components. This is essentially structural JavaDoc. In our case the root class from which the JavaDoc structure would stem in any given mod should probably be the class with the @Mod annotation which most often should be the only class that is named the same as the mod. (not the case in GT5 right now, might want to change that).

#

To document my recent efforts with the cover refactor, the right place would be the Cover class. Having a suitable and sensible place to put this documentation kind of depends on already having refactored the code to have a sensible structure and naming scheme, otherwise it will be less discoverable as you will need to find it from the root.

atomic mist
#

Hmm, yeah Javadoc would be the place both most seen by people and easy to work with. First we can try adding Javadoc as much as we can, then see if it works

sick bloom
#

One thing that can and should be outside the Javadoc would be our guidelines on writing Javadoc.

#

I think the primary need we face now is building out "map of knowledge" to help you find your way around.

cyan spire
#

I agree. having a central "how to get into GTNH dev, where can you find certain components, how do our basic systems work, what design principles do we want to follow, how should we write javadoc" is one thing, and the actual "what is the purpose of ISerializableMTECoverFactorySync" type documentation should just be in javadoc

#

Another question: if we make these guidelines, should we "force" javadoc on new code?
("force" in quotes because it'd be more like "heavily reccomend")

cyan spire
sick bloom
cyan spire
#

Great yepyepyep to give more detail on my experience:

When I find a bug in the pack or am curious how something works, I try to find the solution myself so I can include it in the bug report, (https://github.com/GTNewHorizons/GT-New-Horizons-Modpack/issues/19265#issuecomment-2707237752, https://github.com/GTNewHorizons/GT-New-Horizons-Modpack/issues/16398#issue-2320326506 ) but actually spinning up the current latest local version sounds difficult? I feel if there was a general "getting started with GTNH dev" that would help a ton.
Also with the most basic stuff, like "where/how are mods injected, how to live reload your changes" but also "where in the code (generally speaking) are recipes managed, where are player interactions (e.g. right clicking) handled" etc. Specifically (I don't know a lot of good examples because I don't do gtnh dev yet kekw )

#

A centralized place with all the "how to get started with gtnh dev / bugfixing / new features / etc" would be great, and then the actual nitty gritty can be in javadoc

worldly bronze
#

That is where expierence with minecraft modding in general is useful

sick bloom
# cyan spire Great <a:yepyepyep:880173378206572655> to give more detail on my experience: W...

Thanks for sharing these are all great questions. A wiki article is probably a suitable way to answer most of these questions. It might also be interesting to make videos on the topic eventually.

Here's a couple of rapid fire answers since we're on the topic :

Setting up a development environment

Setting up a development environment to work on a mod can range from trivial to tricky depending on what exactly you're trying to test.

  • If the changes you have to make only affect a single mod, you can easily easily launch that mod's development environment using a provided gradle task (Run Client) and perform all the debugging you need.
  • If your changes involve several mods, you might need to update one mod's dependencies to pull in your changes in the other mod. You can still test everything directly using Run Client.
  • If your changes rely on the fully loaded state of the pack with every other mod interacting, then you do as much as you can using Run Client but can still test your changes in the full pack by updating the instance's jar for that mod to be your own. This could be tricky if your mod also requires dependency updates (gotta update those too). This is usually easier to do on a nightly build of the pack which already has every other mod updated.
  • If your changes involves configs such as quests, you also want to test your changes on a full instance of the pack. The questbook itself is usually updated in-place through an in-game editor. Those config changes are committed to https://github.com/GTNewHorizons/GT-New-Horizons-Modpack
#

Where/how are mods injected?

Check out the cpw.mods.fml.common.Mod and cpw.mods.fml.common.Mod.EventHandler interfaces and their detailed JavaDoc (the kind we need to have)

How to live reload your changes?

https://wiki.gtnewhorizons.com/wiki/Development#Hotswap

Note that this will not allow you to re-run forge initialization events since they only run at game start.

Where in the code (generally speaking) are recipes managed?

tldr; Absolutely everywhere.

In practice each mod is typically going to register items, recipes and other game objects as part of it's handler for the FMLPreInitializationEvent, FMLInitializationEvent or FMLPostInitializationEvent.

In GTNH specifically we often ask mods not to register recipes we intend to override either through configs or through a check to see if the mod dreamcraft is loaded. We then use dreamcraft to register recipes specifically made for the pack.

Where are player interaction (e.g. right clicking) handled?

It depends on what the player right clicks with, there is a central part of the code where all player actions are handled and in some cases a forge event will be sent to find a mod to handle that event, in others like right clicking a block with an item code will run in the block and in the item to determine what should happen. The trick here for any interaction is to find a feature that does something close to what you want and go read its code to see how it does it.

Don't hesitate to ask me to expand upon those, but probably in the #mod-dev channel which right now is essentially the intended answer to all those questions

cyan spire
#

I see, that makes sense yepyepyep And I agree a wiki page that's the "getting started with GTNH dev" startpoint would help
I also realize that this has probably gotten off-topic since the core idea of this threat was setting up processes to improve the state of the code/api during big refactors / tool dev x3

cyan spire
worldly bronze
#

probably best to move to #mod-dev

sick bloom
#

That channel moves awful fast nowadays. I wonder if there would be value in a dedicated #mod-dev-help or #new-modders channel dedicated to answering those questions.

worldly bronze
#

good question

cyan spire
steep nacelle
#

I would make a mod help channel, would be useful

worldly bronze
sick bloom
#

Right now #mod-dev and #github-discussion are basically used interchangeably. You start your new conversation in whichever one isn't already in a debate. They essentially have the same topics though.

worldly bronze
#

more or less dev-general

steep nacelle
#

I think breaking it up into feedback/ discussion and help would be useful

#

Normal mod would be feedback/discussion and mod help would be help

cyan spire
#

Github discussion seems like it's for discussion about PRs, issues, github related things etc but it seems that would veeeery quickly evolve into mod substance discussions tbh

#

and in general it sounds hard to discuss a PR without also discussing its contents

dusk ember
# worldly bronze <@213077777367302144> thoughts?

well if #help can manage helping hundreds of player per day, i'm sure #mod-dev can be of use for devs. As it has been said, most of the talk happening in #github-discussion can be done in #mod-dev and vice versa.

#

in effect we have 4 channels for devs, as #beta-testing and #meta-dev are also a thing

steep nacelle
#

What are those 2 channels

dusk ember
#

semi private channels

#

one you can go in if you select beta tester role, the other if you want to participate in pack dev when ideas are a bit too premature to be discussed publicly

steep nacelle
#

That is true, the AOI thread and those channels are prob enough for discussion so I think mod dev on its own is good

cyan spire
# sick bloom Thanks for sharing these are all great questions. A wiki article is probably a s...

to come back to this, you linked https://wiki.gtnewhorizons.com/wiki/Development#Hotswap, but this wiki page seems to already cover a lot of stuff that I had in mind x3 no idea how I didn't find that before

To contribute back to the original discussion:
a "best coding principles" document (e.g. decoupling, compartmentalization, etc) could be put in here and be respected by people who do PRs to suggest etc

image.png
GT New Horizons
Development