PR workflow suggestion iterative merges or similar?

[jwhendy]

This is certainly bigger than this repo... per the comment made by @davetcoleman in #94 , it seems that Travic CI will fail if files don't yet exist on the current MoveIt! site. Thus, if a file is moved or added, he has to add the file (with the PR merge) to find out if the build will actually succeed.

I'm about an hour in this morning hunting around for various build failure problems. Some might be the result of merging actual build failing PRs (e.g. broken links in #101), but some may very well may be because a previous commit couldn't be tested until merged. Once the surface failure (e.g. missing file) was fixed, some other issue can appear (like extra spaces in a bullet list, like in #92).

These are some possible solutions:

• whatever continues to cause a build failure in HEAD after merging is fixed asap
• alternatively, a failed merge is reverted once the true failure is known and re-merged only once the entire problem is solved
• update the build test somehow (as Dave suggested in fixed collision contact tutorial failing build due to image location… #94)
• some sort of "iterative" merging where the surface failure is fixed (like manually adding a missing .png file) and then re-triggering the build to see if it continues

As for build system improvements:

• I see a lot of "warning treated as error: blah" messages; perhaps non-fatal errors should be spit out as warnings without stopping the build so users can see all of the errors. This way, if they get one that's inherent in HEAD, they can still see anything related to their actual commit. Right now, if I get an error in some file I didn't change, I'm blind to any issues with my work.
• logging errors per file? Not sure if that would be helpful, but sometimes a build fails for some reason, then another merge happens and the reason changes. If it's been long enough (as recently, when I came back from a 10 day vacation), I don't remember the original cause.
• also Dave's suggestion, make the test build against what the site would be if the merge were conducted vs. what the site currently is.

I have no experience with Travis CI, but if someone points me in the right direction, I can take a look. I found .travis.yml, but I don't understand how it's pointing to the "current site" vs. what is generated by the resultant local ./build directory.

Thanks for taking a look!

[v4hn]

On Thu, Aug 24, 2017 at 03:24:24PM +0000, John Hendy wrote: - whatever continues to cause a build failure in HEAD after merging is fixed asap

That's the very-short-term solution I guess.

- update the build test somehow (as Dave suggested in #94)

+1 This would be great, but as Dave pointed out, this is also a bit of work. I believe the other two options add too much overhead to use in practice. We are happy when someone contributes patches for the tutorials, so I don't want to stall contributors with more bureaucracy than necessary. Even if that means maintainers have to jump through one more hoop... :/

- perhaps warnings should be fixed so that users can see *all* of the errors going on.

+1 Patches welcome.

I have no experience with Travis CI, but if someone points me in the right direction, I can take a look. I found `.travis.yml`, but I don't understand how it's pointing to the "current site" vs. what is generated by the resultant local ./build directory.

+2 I don't know much about this either, but it would help maintainers quite a bit if someone would improve the situation here.

[jwhendy]

Thanks for the feedback. I'll look more into CI and see if anything stands out. When I tried to find issues related to "Travis CI fails due to .png file not existing" I didn't get any obvious hits (maybe this). This makes me wonder if something is goofy with how the test is run, or rosdoc vs. sphinx... how would others not have run into the non-existent file issue otherwise?

Anyway, thanks for the guidance and I'll post back in a couple weeks after some free nights to get to know Travis.

[jwhendy]

@v4hn read a little more. Could you point me in the direction of the full process that goes on between this repo and the doc site? I think to really "get this," I would want to replicate Travis on my fork, and perhaps try and create a local doc site that mirrors yours.

This would help for patches, as I'd need to know how files ultimately move. For an example sketch, maybe a hypothetical improvement might be:

## get list of newly added files
git diff --name-status kinetic-devel

## script to send those files manually to the docs.ros site
scp file.png ??

## try the build
sphinx-build
rosdoc_lite

## if success, do nothing; if fail, remove file
ssh -e 'rm file.png'

Total guess, but could possibly handle the new file issue. Either way, illustrating that I need to know how things go from the build dir here to your host server, or maybe the build server is just cloning this, building locally, and then serving from the dir itself?

[v4hn]

As I said before, I don't know any details here. @davetcoleman knows more about that, although I'm not sure whether he set it up himself..

[jwhendy]

Ah, sorry. I took that to mean you didn't know much about Travis, either, not that you didn't know about the git repo -> doc site workflow.