Begin debugging documentation

[Grauldon]

This pull request is not complete and addresses issue #356 and PR #661.

Most changes are contained in the source/contributing/implementation directory. The one exception is a commit adding anchor points to the plugin debugging page in source/plugin/debugging.rst.

The branch began with a fork of PR #661. I decided on a new approach after reading comments in the PR. I changed debugging.rst to a directory so that content can expand over time without having one file too large or creating multiple debugging files in the implementation directory. Furthermore, I created stub files for future improvements based on comments in PR #661.

I reviewed the SpongeDocs the other day for pertinent information and to evaluate the fit of the changes. It seems I am providing too many details for basic steps, and I need to ensure I am not providing information found elsewhere in the Docs. For example, some of the information in the debugging/index.rst file overlaps with the Git Workflow for API and Implementations page.

So, I decided it is time to reach out for assistance, guidance, and feedback.

Thoughts for moving forward

• Separate out command-line vs IDE versions of content (e.g. setup, debugging steps)
• Add subdirectories for certain content (e.g. setup via command line or IDE, mixin)
• Describe functionality in SpongeAPI vs SpongeCommon vs SpongeForge / SpongeVanilla
• Describe mixin, how it is integrated, debugging best practices and how-to's
• Complete stub pages (e.g. Debugging Mixin, Debugging Tools)
• Complete this "project" through multiple PR's by starting with basics and working through a prioritized list

Questions

• Does what I have so far align well with the original ideas for this page?
• Are the pages too short (e.g. combine git, workspace, and ide)?
• What does this comment from PR 661 mean?

Suggest the creation of a test plugin along with the contribution/PR.

• Can I get some input on the prioritized list (if not a provided list)?
• Are there other topics not listed here or in PR Add more stuff about debugging #661 that could be added?
• Can we promote the forum post entitled, Common issues when debugging Sponge?

Disclaimer

I am relatively new to Sponge and learning Java. I do have application development background, although on mainframes. So, please bear with me. I always heard that one way to learn processes and systems is to document them. Some of my documents may come across as too basic or like tutorials; this is why. It is also why I am reaching out for assistance. I want my documents to fit while providing pertinent information. All help and guidance is appreciated!

[phit]

Does what I have so far align well with the original ideas for this page?

dunno, doesn't really matter, whatever the original idea was I think this will be way more useful

Are the pages too short (e.g. combine git, workspace, and ide)?

short pages are easier to navigate imo

Can I get some input on the prioritized list (if not a provided list)?

which list? the moving forward stuff?

Are there other topics not listed here or in PR #661 that could be added?

probably, but you already have quite a few things covered, to not overload yourself, I'd say finish this first and then one can always see what else would be helpful

Can we promote the forum post entitled, Common issues when debugging Sponge?

sounds like a good idea, ill try to bring it up during our next team meeting for the community team to include it in the next status update

---

Separate out command-line vs IDE versions of content (e.g. setup, debugging steps)

I think for at least debugging everyone is using their IDE, setup for both sounds good though

Describe functionality in SpongeAPI vs SpongeCommon vs SpongeForge / SpongeVanilla

like this? https://docs.spongepowered.org/stable/en/about/structure.html

Describe mixin, how it is integrated, debugging best practices and how-to's

not sure if that's out of scope for these docs, mixin is quite extensive, sadly its own docs are unfinished https://github.com/SpongePowered/Mixin/wiki

anything else sounds good to me, ill start reviewing your first draft in a minute and leave notes there

[phit]

don't really wanna duplicate the mixin wiki, but maybe some useful stuff like the java arguments to export mixin in production https://github.com/SpongePowered/Mixin/wiki/Mixin-Java-System-Properties

not sure what this page could contain otherwise, maybe some coredevs have any other pointers what they use commonly to debug mixins that isnt documented already

[Grauldon]

My idea for this page is to address ST-DDT's comments:

Debugging options such as the post mixin class content output (I forgot the command line option for that)
Tools for decompiling the post mixing code (jd-gui or similar ones)
Common issues you might encounter (Broken mixin, NPEs, PhaseErrors with suggestions how to fix them or a link to their respective documentation)
Help with finding the error in your mixin based on the stacktrace (The only help you get is the line number)

and the link you mentioned.

[gabizou]

Likewise, if you use MinecraftDev plugin for IntelliJ, you can debug and step through mixin code without having to deal with outputted class files from the mixin class loader.

I can do a demonstration gif of sorts stepping through sponges changes with both SpongeCommon and SpongeForge intersecting each other.

[Grauldon]

which list? the moving forward stuff?

Yes, the moving forward stuff. Basically, is there any topic more pressing than others? I will probably work on the Mixin stuff later since it seems complicated. But, given the information, I can write the document to include it if the team prefers.

sounds like a good idea, ill try to bring it up during our next team meeting for the community team to include it in the next status update

Thank you!

like this? https://docs.spongepowered.org/stable/en/about/structure.html

Actually, taking it down a level and explaining where certain functionality exists. For example, code for events exist in SpongeForge, SpongeCommon, and SpongeAPI. On the surface, it looks like debugging a problem with the cause of an event should begin in SpongeAPI while debugging a problem with the event registry should begin in SpongeCommon. However, a problem with an event listener could be in SpongeAPI or SpongeCommon.

This might actually already be in the plugin section of the Docs, which is something I realized the other day when I decided I better get some guidance. But, this is what I meant by describing the functionality.

Thank you for the feedback!

[Inscrutable]

This is a promising start. I'm happy with your plan, and it deserves decent levels of feedback. I do wonder whether we should be pointing to https://github.com/spongepowered/spongedocs for new contributors, as we do have a docs page for contributors that helps remind them of our formatting guidelines. Something for us editors to argue about.

[Inscrutable]

I can probably clarify "Suggest the creation of a test plugin along with the contribution/PR.":
Contributions to Sponge should normally include a functional test plugin to demonstrate the feature working.

[Grauldon]

I can probably clarify "Suggest the creation of a test plugin along with the contribution/PR.":
Contributions to Sponge should normally include a functional test plugin to demonstrate the feature working.

Perhaps this topic needs its a subsection under Contributing to Sponge or Developing Sponge. The page(s) could then answer the following questions:

• When to provide a test plugin?
  • PR to fix Sponge?
  • PR to add a feature(s) to Sponge?
  • submitting new plugin through Ore?
• How to provide test plugin?
  • with PR?
  • through Ore?
  • Maven repository?
• Should test plugin be developed for use with JUnit?
• Are there any guidance or requirements/restrictions on using logging vs. stdout/stderr?
• Are there any considerations for plugin identifiers for test plugins?

and other questions that may come up.

Oh yeah! I think if the topic is made a part of the debugging topics, I just add a new page with this PR. Otherwise, should I include it in this PR or a separate PR?

[Inscrutable]

Adding a page to detail test plugins might be justifiable, depending on it's length. If it gets that wordy it would justify a separate PR - and possibly also a good hard look over: how much is necessary? The conversation would help iron out what we do and don't need, and clarify the fuzzy bits.

[Inscrutable]

Some minor corrections and the odd quibble; I'll clean it up myself if you want, when it's ready to merge. I'll let others go over the more technical aspects of this for correctness.

[Grauldon]

OK, this push was intentional! :)

I am currently working on Debugging Sponge Within the IDE (ide.rst) and Debugging Mixin (mixin.rst). I hope to have updates for them soon.

[Grauldon]

Today's push adds content for debugging mixin.

The thought behind including phases, environments, and configurations is that an incorrect/incomplete configuration file can cause problems and the phases and environments support understanding the configurations. I started to take it out but decided to leave them in and see what others say.

The section of a broken mixin can be improved, I'm sure, but I will need help to improve it.

I will work with IntelliJ and the MinecraftDev plugin to add content to the Using section. I just wanted to get the other stuff pushed and start working on the Versioning PR some.

I do have some content for the IDE article, but I am not ready to push that yet.

[Inscrutable]

This is phenomenal work with great scope, but it's also becoming an omnibus PR. As I suggested before, you could do this as several pull requests to break up the work a bit. Many additions and revisions to one PR leads to reviewer burn-out, and it also bundles it all into a single commit if we follow our usual squash-and-merge process. Making smaller PR's (where possible) would also help get something published sooner, and leave us with a more colourful history.
It's up to you @Grauldon - you're the one doing all the scribe-work here. 📜

[Grauldon]

This is phenomenal work with great scope, but it's also becoming an omnibus PR. As I suggested before, you could do this as several pull requests to break up the work a bit. Many additions and revisions to one PR leads to reviewer burn-out, and it also bundles it all into a single commit if we follow our usual squash-and-merge process. Making smaller PR's (where possible) would also help get something published sooner, and leave us with a more colourful history.
It's up to you @Grauldon - you're the one doing all the scribe-work here. 📜

I like your suggestion. How do we proceed? Should I take the [WIP] out of the title? I will watch for reviews for this PR to finalize it. And, I will open new PRs going forward with new material. Thank you for bringing this to my attention!

[Inscrutable]

You could save the IDE article for a subsequent PR, and perhaps also any other bits that are troublesome to complete (broken mixin, MinecraftDev plugin) and delaying progress. I'd suggest removing the WIP (when you're happy to do so) and we can give it a final cursory review and merge it. If you need to you can make issues for unfinished business, so that others can tackle it while you are busy.

[Grauldon]

I changed the title to indicate ready to merge and to reflect more accurately the accomplishments of this PR. I considered "cleaning up" the PR by removing the Using section in Debugging Mixin, removing references to #356, resetting Debugging Sponge Within the IDE to a placeholder file, for now, removing sections without content in Frequently Asked Questions, etc. Please let me know if any of these actions are desired.

I will begin training two weeks from today, and I need to get my work with Sponge down to more manageable projects. I plan to open a new PR soon (hopefully this week) to update content for Debugging Sponge Within the IDE with the latest. So, I hope to have completed these three PRs by the time training begins. Afterward, I will contribute as much as I can.

[ST-DDT]

IMO you should use absolute paths if you have at least two levels of ... Otherwise it looks good to me.

[ST-DDT]

Use absolute paths here

[Inscrutable]

I'm happy to merge this without further cleanup @Grauldon - any unfinished business can get put into issues later, if you don't get the time to PR them yourself. But cover your tracks if you feel the need 😉
📚 I would also like you to join our editing team, if you're up for it. We are always in need of staff (and they get Spongy previews).