I have to create a github-presence for an open-source organization. The aim is to distribute code snippets and reference implementations in different programming languages.

These contributions are going to be (ideally) created by people outside of the organization and should be collected.

I know that good practice is to create one repository per project. To this end, each implementation (in a specific programming language) should be considered a standalone project and should get its own repository. The point is that this approach makes hard for external people to contribute, because github pull-requests can only be made against existing repositories.

By creating a single repository with a subdirectory per programming language code contribution becomes easier, but I'm afraid that some IDEs may complain about the directory layout.

I'd like to know whether someone already solved this very specific problem in a satisfactory way.

  • Would you explain more about the difficulties in allowing external people to contribute? I don't understand exactly what the difficulty is. I read your sentence about pull requests can only be made against existing repos, but I'm not sure why that is a problem in your situation. – Aaron Kurtzhals May 16 '13 at 16:34
  • The problem is that people external to the organization (I mean the github organization) could just oversee that we do accept (and welcome!) contributions, and think that their language of choice isn't supported by the system. – Daniele May 17 '13 at 7:54

I haven't had this specific problem, but I have thought along these lines for a similar upcoming issue at my work.

As you say, a single repo has some nice advantages. Having each language as a directory in the root isn't a bad way to go if you need to keep them all together. Another option would be to create different branches for each language if you're worried about segregation (and possible IDE confusion).

But since you're working in github, you might want to take advantage of their organizational structure and create an organization/group with each language as a separate repo. New contributors adding a new language can just create their own github repo and then notify you to fork it.

| improve this answer | |
  • That's an interesting idea, I haven't thought of this approach. I am afraid that maintaining the forks could be a huge effort as the number of supported languages grows, since we would have to follow the changes in the source repositories and merge any addition/bugfix/etc. – Daniele May 17 '13 at 8:05
  • Well, once you fork a contribution then your fork would be the "master" that everyone works on. You wouldn't necessarily need to worry about the other forks (including the original). Contributors can work directly against your main repo or submit pull requests from their forks as desired. So the number of repos you care about would only equal the number of languages you're willing to support. – Allan May 17 '13 at 15:37
  • +1 for suggesting to create Organization in GitHub and then have all repos enclosed. – Kushal May 28 '13 at 9:16

You want to distribute code snippets and reference implementations. By nature, these are not compile-able. I can assume the following are true:

  • An IDE will not be able to serve your needs anyway, since the code will be incomplete
  • Code for each language will have further segregations. e.g. categories or tags. So there will be some extra folder structure for each language

Given the above two, having a single repository will likely complicate things. You either have to go for multiple repositories (safest approach), or go for a single repository with different branches. And forget about the code being cleanly editable in an IDE.

I'd suggest go for separate repositories for the following reasons:

  • It becomes easier to manage Issues for each language
  • You can give specific open source contributors access to some of these repositories. For e.g. a prolific Java contributor can be given access only to the Java repository
  • Free up your branches for other stuff (e.g. versions of the same language)

Its premature to worry about contributors not being able to create new languages. You could already create empty repos for most of the popular languages, and you can have some kind of Form in your site to raise a request for new languages.

Edit: Minor Clarification

| improve this answer | |
  • In fact we plan reference implementation to be compile-able, hence we took a slightly different approach that I documented in my answer. Thanks! – Daniele May 28 '13 at 8:59

Thanks for the proposals, they helped us a lot to find a good compromise.

Here is what we came up with:

Since the code snippets are just tiny parts of code, that probably could not work by themselves, this repository may be shared across languages.

Reference implementations, on the contrary, are likely to be self-contained and in this case it makes more sense to have a single repository per each language.

In my opinion the use case for the code snippets is "clone and study": the snippets should be used for inspiration and small tests, hence I think it's acceptable to go and look your language of choice. In most cases people will just look it up on the github website, I guess.

The use case of the reference implementation is "clone and run". I expect a reference implementation something that I clone in my IDE and start extending. In this case having a repository per language is of great help.

I think it's a good compromise also because I expect the reference implementations to be much less wrt the code snippets, hence the effort of following the corresponding source repos is not that high.

In case you are interested, the github organization is alpinebits: a definition of an interface, based on OTA and fitted to the Alpine Tourism, for the exchange of touristic data.

| improve this answer | |

Not the answer you're looking for? Browse other questions tagged or ask your own question.