Development documentation
-
Not sure if documentation really counts as development, but it is as close as I can get for now! And it could be useful for others.
There are a few documents that I feel can be better or clearer for newbs like I am. I was thinking about updating some of them, and was looking for advice on layout, formatting, hierarchy, etc.
First one that I would like thoughts on - typical git workflow.
I know that it is probably faster, but CLI is kind of intimidating to me as a newb. I was thinking about making something like this for the IntelliJ GUI (maybe Eclipse later on). Would I want to make a new document for this? Somehow edit it into this document? Something else entirely?
I was thinking about updating the first readme file as well. A little more beginner friendly step by step. And since I have just set it up for the first time ever a few weeks ago, maybe a few more steps. Showing how you do things like connecting to Github from in IntelliJ, and can then create local clones there.
I think there was something else I was thinking of as well, but can't find it now.
Thoughts?
Suggestions?
Any other documents that could do with a beginner friendly once over? -
I'm really happy you're dipping your toe so seriously into the development waters. It's good to see.
The git workflow document is really to describe that we have a feature branch workflow. There are others out there, there are different branching strategies one can choose. Ours is pretty simply, update master to latest, cut a feature branch, make changes, commit & PR that back into master (rinse-wash-repeat)
There are a dozen git-UI tools out there. It's probably better to find good tutorials on how to use those and simply link to those tutorials. It's much better when we can find someone else's documentation. Less is by far more, anything we have is more stuff to maintain, update, and it clutters up the other content which makes that harder to find.
I'm interested in your ideas about how to organize the dev-docs and the getting started, the first readme file, etc... Keeping things really concise & minimal I do think is the way to go.
I'll admit that I don't have the right context to know what people need the most help with. I believe most developers ought to use Git CLI, the GUI tools slow people down and makes it harder to understand the core concepts that making branching easy. It's really not that difficult once a person understands the concept of a branch, commit, and knows how files changes are attached to the commit-tree.
With that said, I'm a bit torn as how-newby friendly we can make it. In part the setup is meant to be for other developers that do have some notion of what they are doing. It's there so you don't have to reverse engineer from scratch how to do everything, but we just lay it out "here is how you build, how you run the project, and this is the workflow for making changes." The rest is probably best as linked content (for example "Unfamiliar with Git? See this youtube video, this blog post, this post, consider using this tool, etc..)" For example, Eclipse has it's own git tooling, we don't necessarily want to have to document how to use that, and when Intellij updates, we don't want to have to keep pace there either.
With respect to how much experience a person should have, I am a bit torn. TripleA is a whole lot of simple code that has become tangled in knots. It looks easy at first, but then it's actually quite the tangle. Someone completely new probably would benefit from some guidance of how to approach it. I kinda wish there were a list of features that would be easy to add, but in part the tangle is from having relentlessly added feature after feature without coming back and re-working the core code base to keep it simple. Complexity grows exponentially relative to the number of features and lines of code unless there is care to pay down that complexity so that it is a linear or sub-linear growth in complexity.
In short, I think the most important things is that the dev docs are a quick-start guide, not necessarily a "we'll teach you how to dev guide". It should outline the dev process, and how someone should go about making changes. Notably we want most changes to get some discussion first before someone goes to the trouble of actually making those changes (ie: create an issue to discuss & forecast upcoming changes). Beyond that there are some notes and intricacies about the TripleA build, those kinds of things are project specific and should be mentioned (like for example, a person needs to install docker and launch their local database with it, and we have for example a 'verify' script that lists all the verification steps that needs to be run and can be executed itself to do a build verification locally).
-
@ff03k64
I would use and appreciate a document for how to setup IntelliJ and which SDK to use and any other programs specifically for running/compiling Triplea code locally on my PC. -
@TheDog https://github.com/triplea-game/triplea/blob/master/docs/development/ide-setup/intellij-setup.md
I haven't gotten to running and compiling the code myself yet. I would start here though https://github.com/triplea-game/triplea/tree/master/docs
-
This might be even better of a starting point: https://github.com/triplea-game/triplea/tree/master/docs/development#developer-setup-guide
Installing intellij is pretty easy. Once you've done that, you clone the code (you'll need to install a git client), and then in IntelliJ you select "open" > "project" and then select the build.gradle file and it should auto-configure everything. From there, there is a 'launcher' that you can use to compile and run the game.
-
-
@rainova
In short no, Im not a developer.But I will help with testing the Devs work.
This year Im committed to producing a TripleA game with Ebbe called The Shogun with a basic and an advanced version.
-
@rainova I could use a bit of help getting the dev going.
When I run./gradlew :game-app:game-headed:runI get the following error:
java.lang.NullPointerException: Cannot read field "bindingsWhenTrue" because "currentBindings" is nullTurns out that Gradle/Lombok has issues with Java 17, which I ran into.
Apparently, I can delombok the '@Singular' or update the project to Lombok 1.8.21 (well, 1.8.22 is latest).
https://github.com/triplea-game/triplea/tree/master/docs/developmentAny thoughts/suggestions on how to fix that gradle build error?
-
@1infvs2 I ran into similar issues. The Triplea project is on Java 11 - including grade.
Change to Java 11 and you should be fine
-
@rainova Yeah, I should have checked the build.gradle first for the JavaVersion; before building a new VM.
Thanks. I created a pull to update the dev doc and help remind the next person. -
@1infvs2 perfect
