Use git-source-track to track updates to examples

[virtuald]

See https://robotpy.readthedocs.io/en/2019.1.2/dev/porting.html#using-git-source-track

[virtuald]

@fletch3555 I think this would be a useful thing to do since you're reviewing existing examples

[fletch3555]

Oh interesting. A very similar thought crossed my mind the other day, but I didn't realize this tool actually existed. Yeah, I'll take a look.

[fletch3555]

@virtuald, when I run that command, it prepends that line to the file above the shebang. I can submit a PR to change the positioning, but where do we want it instead?

1. immediately after the shebang?
2. end of the file?
3. somewhere else?

I'm partial to end of the file, but not hard-set on anything.

[virtuald]

It can be any line in the file: https://github.com/virtuald/git-source-track/blob/master/git_source_track/cmd.py#L201, it just defaults to the first if there's no validation line.

Previously we did it at the beginning before the copyright line, which I think looks nice. https://github.com/robotpy/mostrobotpy/blob/aabdb769c211f87e74c351478f4778a9fd45df84/subprojects/robotpy-wpilib/wpilib/wpilib/adxl362.py#L1

I think end of file is fine too.

[fletch3555]

Yeah, I'm thinking more the default place it'll create the line if it doesn't exist (which it won't for any of these examples until we start adding it). I'm hoping to avoid having to validate each file, manually move the line, then commit.

I also like it above the copywrite line, but it can't be above the shebang without breaking the ability to just run ./robot.py [args]. That said, none of the files are marked executable at the moment anyway, so I don't know how many people are doing that over python3 robot.py [args]. Perhaps the shebang isn't necessary at all?

Also, putting it in that header (shebang + copyright) breaks the automated header validation.

Either way, end of the file is super easy to implement in cmd.py and bypasses the problem entirely. If you're cool with that, I'll open the PR momentarily.

[virtuald]

I personally always do ./robot.py :) Some of them used to be marked executable, maybe that broke with your rename?

I think end of file is probably fine for the examples.

[fletch3555]

Some of them used to be marked executable, maybe that broke with your rename?

I only looked at one, so probably just missed it. I can commit them all (the robot.py at least) as executable while I'm at it if you'd like

[fletch3555]

And 💥 goes the dynomite: https://github.com/virtuald/git-source-track/pull/9

[virtuald]

With git-source-track 0.4, you can use the following .gittrack file:

[git-source-track]
upstream_root = ../allwpilib/wpilibjExamples/src/main/java/edu/wpi/first/wpilibj/examples
upstream_branch = main
upstream_commit = xxx
validation_root = .
default_location = last

For older examples, I think it would make sense to make the upstream commit match 2023, add the annotations, then update allwpilib to 2024 and do the git source-track diff filename to see what changes have happened in the last year, and update any validations.