Ordering of child elements (artifacts, tabs, and tasks) of a job

[rkrisztian]

I have a problem with the ordering of child elements under a job in your examples, let me reason why.

Original ordering:

          jobs:
            csharp: # name of the job
              resources:
               - net45
              artifacts:
               - build:
                   source: bin/
                   destination: build
               - test:
                   source: tests/
                   destination: test-reports/
               - test:
                   source: coverage.xml
              tabs:
                report: test-reports/index.html
              tasks: # ordered list of tasks to execute in job csharp
               - fetch:
                   pipeline: pipe2
                   stage: build
                   job: test
                   source: test-bin/
                   destination: bin/

               - exec: # indicates type of task
                   command: make
                   arguments:
                    - "VERBOSE=true"
               # shorthand for script-executor plugin
               - script: ./build.sh ci

So this ordering prefers artifacts -> tabs -> tasks. When I read a configuration like this, I got the following problems:

• What generates these artifacts? How are they derived? Why do I need to start reading the config with these questions in my head raised from the start? (Casuality order.)
• It's not the first thing I want to know when I check what a job does, because it's not what gets done first. Artifacts are only generated after executing the tasks. And Artifacts aren't the first things you write either, but the commands. (Timely order.)
• More often than not, the artifacts are the least important things to check in a build configuration. Then I will have to scroll down, and find what I really need. (Importance order.)

So what I miss here is a sort-of Given-When-Then structure, meaning like, with these resources and environment vars, when I execute these commands, I want GoCD to store these artifacts, and these tabs should be created from those artifacts. Which leads to my preferred ordering tasks -> artifacts -> tabs. I don't think one writes tests like, expectations first, and only then what is executed, as that would be weird too.

The reason this is important to me is, your example codes essentially impose a recommended style, which people follow. Thus I find it important that the examples are in good shape.

Also, not everyone thinks this is an important readability concern, which I find weird. Maybe we should discuss, as I'm trying to see why this styling should rather be viewed as highly opinionated.

Thank you for your consideration in advance, all I can ask.

[tomzo]

@rkrisztian I agree with you that order of tasks, artifacts, tabs makes more sense. But as you said, I have never noticed this as an issue until you mentioned it here.

your example codes essentially impose a recommended style, which people follow.

I never intended these examples to be a recommended style, but rather a quick start to show things could be done. But its probably true that copy-pasting is happening a lot and people tend to follow what's in the readme.

@rkrisztian have you actually implemented a different style in your projects? Would you say that it did have a positive impact on readability? Have you received any feedback about it?

[rkrisztian]

Yes, the power of copy-pasting should never be underestimated. Examples don't just share/recommend code, they also ad-hoc serve as sharing/recommending coding style, like it or not. Because every time I bring up styling issues, people often point to the original examples as a reference. That also happened to Gradle, where their examples don't use the same coding style consistently. It's hard to argue against that, because different style in a project yields a harder learning curve (you also have to learn a different coding style). I just go with common sense, and whatever helps maintainability with as objectively argued as possible.

However, I can hardly give you useful stats/numbers, because I never measured them. I know one guy who agreed with my recommended ordering in my company, but that was like a year ago already. I know one guy who saw a longer job definition from me written in my recommended order, and he agreed that it was indeed quite nice to read that way, but that's all the feedback I got that is not about, they don't care about the order, they are very neutral about it, they don't find it important, or they gave the same argument I feared above ("not the official style"). Which I heard plenty of times. Furthermore, I also heard some reasoning towards the current official ordering: "this is my personal preference, because I edit tasks the most often so they should go last" (not objective reasoning that I would definitely avoid) and "it helps for me to have smaller indentation jumps after the task definition parts" (something like that, I can't remember clearly anymore).

I don't know, you have much more power to decide and improve things, than I will ever be, where I'm bound by budgeting limitations and priorities. It's hard for me to convince people when YAML code is less frequently edited and maintained than regular code, so the effort spent on such discussions can have less turnover on the long run. And that is probably why I should drop it too, if this discussion gets longer and longer...