Gitea: Template Repository

[lunny]

A repository could be a template repository.

• [x] You can change a normal repository from or to a template repository.
• [x] You could do anything with a template repository like you do that with a normal repository.
• [ ] When creating a new repository, there is a list of template repositories you have permission to visit. You can pick up one and click create, and then you can chose which template repository's items (git/wiki/labels/issues/prs/settings/hooks) will be copied to new repository.
• [ ] You could use variable replacement on template repository's files. https://github.com/go-gitea/gitea/issues/7365#issuecomment-508971493

This will replace #2062 #7359 .

[silverwind]

Feature idea: Variable replacement in a template repo's file. For example, variables such as:

• {{REPO_NAME}}
• {{REPO_OWNER}}
• {{REPO_HTTPS_URL}}
• {{REPO_SSH_URL}}

These variables could be one-time replaced at creation time. As far as I know, GitHub's template feature does not support such a feature yet.

Copying non-git content should be optional. It brings problem of what to do with absolute URLs that point to the template repo itself. Not sure we should even attempt to rewrite those.

[davidsvantesson]

Feature idea: Variable replacement in a template repo's file.

Current readme template already support {Name} and {Description}. I think it should be the same variable replacement for template repos but in all md files (and possibly other file types as well, maybe configurable)

Copying non-git content should be optional. It brings problem of what to do with absolute URLs that point to the template repo itself. Not sure we should even attempt to rewrite those.

I agree it would be error prone to try to fix URLs, but instead more generic variables could be added to settings. For example the _External Issue Tracker URL Format_ already support placeholders {user}, {repo} and {index}.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs during the next 2 weeks. Thank you for your contributions.

[davidsvantesson]

Too good idea to be closed. :green_heart:

[jolheiser]

When creating a new repository, there is a list of template repositories you have permission to visit.

That could be quite a large list (especially for admins). Why not do it how GitHub does, where it's a Generate using this template button on the template's page?

all template repoisitory's conent (git/wiki/labels/issues/prs/settings/hooks) will be copied to new repository

I agree with @silverwind that only git content should be copied (at least at first?)
When creating a new repo using a template, the screen to create the repo could be almost identical to making a new bare repo. You can name it, make it private or not, and give it a description.
Since most of the init things would be taken care of by the template, the only other field I can think of is adding a label set at creation time, but in my opinion this should be a field when creating, not carried over from template.
Issues/PRs don't make sense to copy (in my opinion) because those would be issues/PRs towards the template, not necessarily the project you are using the template for.

[guillep2k]

Wikis and avatars are things that could come from templates as well. I use repo avatars to convey the type of repo it is (e.g. library, utility, firmware related, electronic, mechanical, etc.).

IMHO this function could be emulated by a migration from the same instance. The admin/org owner can have as many template repos as they want and clone them by migration gitea-to-gitea. It would be cool if Gitea would let you choose what items not to migrate (e.g. not issues or not teams).

[davidsvantesson]

That could be quite a large list

It can be made searchable, but I agree it is a good idea to at least allow selecting directly on the template repo.

It would be good to allow selecting what content you want to copy (or not copy) from the template repo.

[jolheiser]

• [x] Git Content #8768
• [x] Git Hooks #8926
• [x] Webhooks #8926
• [x] Topics #8768
• [ ] [Auto-Expand](https://golang.org/pkg/os/#Expand) specified variables
• [ ] Avatar
• [ ] Issue Labels
• [ ] Wiki
• [ ] Issues/PRs (in my opinion these shouldn't be part of a template generation)
• [ ] Teams, contributors if new repo owner == template owner.
• [ ] Branch protection settings (i.e. protection status; white lists too if new repo owner==tmpl owner)
• [ ] Protect branch rules (for default branch)
• [ ] Repo permissions
• [ ] Squash the commits. When create a repository from a template repository. We may want to squash all the commits on the template repository as one commit may has a default commit log init project. And the author and committer is the repository creator. (hesitation)

[guillep2k]

Started at #8768
Not closing this issue with the PR because it doesn't implement all the use-cases here.

@jolheiser I'd add to that list:

• [ ] Teams, contributors if new repo owner == template owner.
• [ ] Branch protection settings (i.e. protection status; white lists too if new repo owner==tmpl owner)
• [ ] Single (default) vs. all branches

[davidsvantesson]

Some more to make the list complete:

• [ ] Webhooks
• [x] Topics
• [ ] Releases (Maybe not very useful?)

[lunny]

• [ ] Protect branch rules
• [ ] Repository permissions

[davidsvantesson]

Regarding the variable replacement, I think there are two possibilities. Either make a new commit with the variables replaced, OR replace every time the markdown is rendered in the UI. Both options have some pros and cons. I prefer the later, but it would not work as well with other git services.

[jolheiser]

Regarding the variable replacement, I think there are two possibilities. Either make a new commit with the variables replaced, OR replace every time the markdown is rendered in the UI. Both options have some pros and cons. I prefer the later, but it would not work as well with other git services.

The replacement would happen at generation time in the same initial commit.

[jolheiser]

@guillep2k @davidsvantesson

I don't think branches or releases can be carried over, as both of those rely on commits that won't exist once the repository is generated.

A generated repository acts like an initial commit based on the files in the template at the time of generation. It doesn't keep the history of the template repository, as it may have no meaning to the generated project.

All of the above can be changed (and made optional) by someone else, however it is not my current intention for this implementation.

[davidsvantesson]

That was not my impression. There can be two possibilities for how a repository is created from a template:

• Clone the repository including history
• Copy the files of the tip (HEAD) of master branch

I think the first shall at least be an option! History of the template might be interesting for the created repository or not. However the main point of cloning rather than copying is that if someone later change the template, it will be much easier to merge in those changes later as git keeps track of was what changes since you created from the template.

[jolheiser]

That sounds like a fork or migration imo

I think we are having different ideas of what a template is and what to use it for.
In my opinion, it should be a starting place for a new project and nothing more.
Merging in upstream template changes makes no sense to me once I have started work on the generated project.
If you mean keep a personal copy of the template to merge upstream changes from, that would be forking the template and adding your own commits to it.

EDIT: I think we are starting to split hairs, but this is a good conversation to clarify how future PRs may (or may not) be implemented.

[davidsvantesson]

In the PR you said something about you shared code from the forking process, so I somehow thought it would be a cloning process :) (I havn't checked the details of the implementation yet).

Forking in Gitea (and Github) usually means you intend to contribute back to the original repository. In GitHub I don't think you even can choose to fork to the same user as owns the repository? So I don't think that has the same usage. At least I don't want to keep it as a tracked fork because normally there will be no pull request back to the template. Migration is in my view more used between different sites, even if it is possible within one site. So maybe that is more close to what I expect.

My idea of a template is that you can have set up some basic software structure (maybe even a complete rudimentary software) that you use to make other software from. The history can be interesting if you want to know why something was made in a certain way. If someone makes an update to the template, you might want to try merge it back (so that is the opposite way than a normal pull request).

[jolheiser]

Oh! That's my bad, I maybe worded it poorly.
It shared code in the sense that it is a repo based on another repo, but there are key differences because if the implementation.
Sorry for the confusion.

I agree the history is nice to see, however that's partially what the "generated from x" sub-title is for, since the commit history makes sense for the template (but not necessarily the generated project)

This process very closely resembles how GitHub uses templates. (Maybe not code-wise, but in terms of the end result)

[guillep2k]

Regarding the copy of all the branches and/or the history, my view is as follows:

• Only HEAD from the default branch should be copied as this is only a template, after all, and one might want to start a repo with a clean history.
• The first commit of the repo must be done under the name of the one creating it (i.e. history needs to be rewritten).
• All the branches in the template should be created in the destination, pointing to HEAD, like master.

I think that copying branches is useful, and I'll give an example to illustrate my idea. Imagine a template (in Gitea from the future! 😄) with:

• a master branch (default), protected, requires approvals from team X to merge.
• a dev branch, protected, no approvals required but can only be merged through PRs.
• a QA branch, protected, requires approvals from team Z to merge.

What I mean is that an org can have all the permissions already set up for the template according to their usual workflow, and when they create the new repo these permissions are carried onto it. Of course this only applies if permissions are copied too.

[jolheiser]

@guillep2k I see what you mean now, and I agree. 👍

[lunny]

• [ ] Squash the commits. When create a repository from a template repository. We may want to squash all the commits on the template repository as one commit may has a default commit log init project. And the author and committer is the repository creator.

[jolheiser]

Regarding auto-expansion of variables in content, what should all be mapped (and what content should be affected?)

I'm thinking git content and git hooks currently. (Probably the wiki in the future as well, but that's almost an entirely separate beast)

For mapping, I was thinking of giving it the entire models.Repository but that might not be a wise decision. e.g don't SELECT * when you can choose what fields explicitly. :wink:

Per @silverwind (modified to match what os.Expand expects)
${REPO_NAME}
${REPO_OWNER}
${REPO_HTTPS_URL}
${REPO_SSH_URL}

Anything specific to a repository I would probably also make the same variable available as old and new.
e.g.
${TEMPLATE_NAME} and ${REPO_NAME}

[lunny]

@jolheiser Could you add https://github.com/go-gitea/gitea/issues/7365#issuecomment-552491746 to you to do list?

[jolheiser]

@jolheiser Could you add #7365 (comment) to you to do list?

I can, but if I understand it correctly it may not be needed. Currently there are no commits to squash because the newly generated repository abandons the history of the template.

[jolheiser]

@lunny Could you add https://github.com/go-gitea/gitea/issues/7365#issuecomment-548647643 to your description so it's easier to jump to what is and isn't implemented yet?
Alternatively, I could open a new issue to continue this one so that I can update the head comment.

[lunny]

@jolheiser We need a feature on gitea to transfer an issue's owner. :) Please open a new issue and I will close this one. Let's discuss there.

[lunny]

Continue on #9126