Links to Private Repos in Public Repos

src-d / guide

Aiming to be a fully transparent company. All information about source{d} and what it's like to work here.

Creative Commons Attribution Share Alike 4.0 International

293 stars 102 forks source link

Links to Private Repos in Public Repos #369

Open dmitryvinn opened 5 years ago

dmitryvinn commented 5 years ago

Throughout the public repository, I found quite a few links to the private repos which obviously greeted me with a 404 page from Github. Personally, I do not think it is the best experience for those who are outside of the organization.

I was thinking about potential options:

Do nothing (i.e. leave things as is)
Remove linking to the private repos (i.e. instead of src-d/issues-general, just use src-d/issues-general)
Do not put links to the private repos at all
Open all private repos referenced in public repositories (probably, not an option for most)

Personally, option 2 sounds fairly decent, but if we consider that this guide is primarily intended for internal use (i.e. those with access to all private repos), then option 1 is good enough.

Note: Example of public repos with private links: https://github.com/src-d/guide/blob/master/engineering/teams/methodology.md

dpordomingo commented 5 years ago

More examples of public content linking private content:

we link backlog milestones in repo PRs and issues (e.g. https://github.com/src-d/sourced-ui/pull/106)
we link minutes in repo issues (e.g. https://github.com/src-d/sourced-ce/issues/2#issuecomment-496179009)
we link google docs in repo issues (e.g. https://github.com/src-d/sourced-ce/issues/131#issue-464186015)
we link slack conversations in repo issues (e.g. https://github.com/src-d/sourced-ui/issues/11#issue-439649998)

I see the problem, from the external visitor, but the pro is that it increases and enhances internal communication. Removing such links will make more difficult to find that info. But yes, we should aware of this limitation in order to provide meaningful info to external contributors or users.

dmitryvinn commented 5 years ago

Thank you for adding more examples!

Yeah, I agree that it streamlines work for internal contributors; hence, I mentioned option #1 as a valid choice, but wanted to know what others think about it.

Let's see if there are any other opinions on this one - if nothing changes, we will just stick to option 1 for now and try to avoid adding more links to the private repos in the future.

Does it sound reasonable?

smola commented 5 years ago

Some comments about specific cases:

src-d/issues-general and src-d/issues-infrastructure are not even used anymore, so we should replace them with current links.
for links to backlog, I always prefer to add references to issues from the backlog epics, this creates a backreference in the public issue that is only visible to people with permissions.e
other cases in issues are trickier, and just not having any reference at all would be worse for us.

For the guide, maybe we could always highlight with a [private link] suffix any link that leads to private repositories. This way at least it's obvious to the reader that it's an internal resource.

dmitryvinn commented 5 years ago

I think it is a great idea - let's append [private link] to the private links! Unless there are any objections or other ideas, I will be closing the issue.