It wasn't public code, so no links handy, but the implementation was pretty much what you'd expect.
For checking referential integrity, make a list of all references and a list of all referents and diff the two. Trivial with git grep and a little bash, but pick your poison.
For surfacing connections, it was a matter of finding them in changes (which was approximately piping git diff to grep) , finding the corresponding locations in the whole repo, and then adding those locations to the PR, for which I used the github Checks API (you can add annotations in the output of a Check Run, see https://docs.github.com/en/rest/checks/runs#create-a-check-r...).
> why do you think most people are against docs living inside the repo?
For internal docs, I think it's an impression that Notion or Google Docs or Confluence or whatever is "easier", although it's usually been easier to get some measure of buy-in for at least some set of internal docs.
For external docs, it's "of course we can't teach git to anyone but engineers!" Which hasn't tracked my limited experience in trying to do so, but it can be hard to get them to try to learn in the first place.
Gotcha, apologies for all the questions - did you implement this for your company?
That's interesting that the reception you got was primarily against documentation inside a repo. Maybe Gitbook could've been a good compromise? I recently made this post on reddit https://www.reddit.com/r/devops/comments/v6yuu5/whats_your_d... and many of the comments prefer to have documentation in the repo.
No worries at all, it's half of what we're here for :)
> did you implement this for your company?
On a couple repos, yeah.
> many of the comments prefer to have documentation in the repo
I think there's a lot of us, but I also think we're more likely to want to talk about it, so it seems like there's more of us than there are.
I should say that I think most everyone's on board with a small amount of developer facing docs in the repo, especially a README and build instructions; whereas if I had my druthers, it'd even include pamphlets the sales team takes to conferences.
True. Seems potentially very useful, but only relevant if you're using GitLab and want a relevant format (or something you can reasonably produce from a relevant format, although tooling questions then get potentially more complicated).
It wasn't public code, so no links handy, but the implementation was pretty much what you'd expect.
For checking referential integrity, make a list of all references and a list of all referents and diff the two. Trivial with git grep and a little bash, but pick your poison.
For surfacing connections, it was a matter of finding them in changes (which was approximately piping git diff to grep) , finding the corresponding locations in the whole repo, and then adding those locations to the PR, for which I used the github Checks API (you can add annotations in the output of a Check Run, see https://docs.github.com/en/rest/checks/runs#create-a-check-r...).
> why do you think most people are against docs living inside the repo?
For internal docs, I think it's an impression that Notion or Google Docs or Confluence or whatever is "easier", although it's usually been easier to get some measure of buy-in for at least some set of internal docs.
For external docs, it's "of course we can't teach git to anyone but engineers!" Which hasn't tracked my limited experience in trying to do so, but it can be hard to get them to try to learn in the first place.