There are a few problems with the permissions setup right now:
I. The documentation on Project vs. Repo permissions is poor. I understand that you guys want to keep this simple, but this doesn't give me enough information to predict what combinations of Project (P) and Repo (R) permissions will do:
In particular there's nothing about whether repo permissions override project permissions or vice versa. This should be made VERY clear in the docs. The only place I see it listed is in the one sentence at the top of the repo permissions screen, but some example in the docs would be really useful.
II. It appears that you can only expand permissions using repo-level permissions, but the UI is misleading. Here are two similar situations:
A. Expanding permissions:
1. Add a user to the project and give him read permission (call this P+r-w)
2. Add a user to a repo in that project and give him write permission (R+r+w)
Result: User can push changes into the repo.
B. Restricting permissions:
1. Add a user to a project with write permission (P+r+w)
2. Add a user to a repo within that project with read-only permission (R+r-w)
Result: User can STILL push changes into the repo.
A makes a lot of sense to me, but B does not. For B, the result is unintuitive because the UI shows an explicitly UNCHECKED "write" box for that user on the repo. But he can still write.
I see two things you can do to fix this:
1. Disallow (B) by not allowing write to be unchecked when a user already has project-level write permissions.
2. Allow (B) and make the explicit repo-level permission take precedence over the project level permission.
Personally I prefer 2, because it gives the repo admin more power to restrict access to certain members of a project team. You can also take it further and allow repo admins to uncheck read without deleting the permission for a particular user, and this would allow you to restrict writing too.
In general, having both project and repo permissions is confusing because I have to look at two screens to understand what is going on. But, it's also very useful to be able to set defaults.
You could solve this very easily by making implicit project permissions show up automatically on the repo permission list. Perhaps they could be faded to indicate that these permissions are inherited, and they wouldn't have an 'x' button to remove them.
If the UI did this, I could look at the repo screen and see exactly who has access to the repo and who does not. Also, a repo admin could very easily check and uncheck boxes on the repo screen, expanding or restricting project permissions as he/she chooses.
This is more powerful than what the current UI allows, and I think it's more intuitive. There is one simple rule to remember: look at the repo screen to see who can access your repo.
One final corner case: if a project permission is deleted, then the corresponding repo permission should go away if it still corresponds to the default. If the repo admin has restricted or expanded it, the explicit change should stay on the repo to reflect the repo admin's intent.