Git repo layout and naming suggestions

Code layout

I've noticed a few plugin repos include the named plugin directory nested inside their repo (example), rather than having the repo root be the plugin directory (example). 

I think the root layout is far preferential because this lets you clone and work with multiple repos directly inside your mod directory. In the nested model, one has to copy the plugin directory into place and copy changes back and forth while working on it.

The nested model has one small advantage, namely you can have your repo named differently than the plugin directory (e.g. plugin name "myplugin" and repo name "Elgg-my-plugin-1.8"), but IMO the advantage of the nested model far ouweighs this.

Repo naming

There are two basic models here: you can name your repo identically to the plugin directory name (example), or differently (example).

The identical model gives the advantage of being able to clone directly into mod without naming the target directory, but I see this as a minor win. Many of us have repos that don't contain Elgg plugins, so here the different model allows us to have sanely organized github accounts.

My only suggestion is that, when naming your repo differently than the plugin directory name, you include a note in the README telling the user what to name the directory when cloning (example).

--

Is this an area where we could come up with some recommendations and get them into the Elgg wiki?

  • I'm going to go ahead and declare the root model to be the correct way to layout your plugins on github. The nested model is incorrect and bad practice, for the reasons you gave.

    My naming convention for repos is always elgg-plugin_name. I highly recommend others do the same for the reasons you gave.

    If you find a good spot on the Wiki to insert these recommendations, that is fine by me. Perhaps a page that gives an overview of Elgg's presence on github, including recommendations on submitting pull requests and such. http://docs.elgg.org/wiki/Github would work, for example.

  • So, in case someone chooses the root model but names the repo differently... what do you have gained then? Wouldn't you need to rename the folder after cloning, i.e. no advanced compared to the nested model?

    A disadvantage of the root model is that the folder name gets lost when downloading (not cloning) the repo. So you need to add information how the folder needs to be named - and people need to see this info. There already have been questions asked here at the community site why plugins downloaded from github don't work. Mostly it was because the folder name was wrong.

    What if you have a plugin repo for an Elgg 1.7 version of a plugin and another repo for the Elgg 1.8 version? The name of the plugin is the same. How would you be able to choose the identical root model in this case?

    Regarding the disadvantage of copying the files back and forth when using the nested approach: you could simply create a link in the mod folder that points to local repo folder - at least that's how I'm doing it when needed. I prefer to keep all repos in one folder locally and not spread them between several different test installations.

    Btw. I have chosen the nested approach. The reasons I have already mentioned: different repos for the same plugin aiming at different Elgg major versions and to be prevent the correct plugin folder name getting lost. Another reason is that I can include the readme file and the license file both in the nested folder and in the root folder of the repo. The files in the root folder stick out. Maybe the chances the readme gets read BEFORE the plugin gets installed (or read at all) are at least slightly better this way.

  • It's trivial to name the target folder in the git clone command, therefore you can use descriptive repo names with the root model. I'd like a repo naming convention so that we can easily tell when cloning what to name the target directory. Here's one possible convention:

    When naming your repository, it's recommended to start with the plugin directory name, then add any desired words separated by hyphens, such that each added word contains at least 1 uppercase letter or period. E.g., for the plugin directory "my_plugin", these repo names would be desirable:

    • my_plugin
    • Elgg1.8-my_plugin
    • my_plugin-Elgg
    • Elgg-my_plugin-1.8

    Notice how, in the above names, the plugin directory name can be easily guessed, or programmatically determined by matching a pattern like /\b[a-z0-9_]{3,}\b/.

    Any other ideas?

    Using a symlink is a good workaround for the nested model, but is problematic for IDEs that let you work on remote code with a local cache. Also with the root model there's nothing stopping you from linking in the repo from a central location as you described.

    W/R/T problems with name mismatches, maybe a plugin_id element should be required in the manifest, so a helpful error message could be displayed. I'll throw this in trac.

    Anyway, non-programmers should be discouraged from installing code from repositories, and the archive files released as community plugins SHOULD be named like the target plugin directory, not the repo to avoid this problem.

  • The pattern I gave above would not match plugin IDs with uppercase chars. Anyway, I've submitted a ticket to add an "id" element to the manifest.