Collaborators and Organizations #82

I suggest we spend some more paragraphs pointing out the advantages of Organizations and explain the roles involved (Owner, Admin, Teams) a bit more.

I have to admit I'm not too confident on that topic...

But I'll give my best!

I'm wondering what can owners do that admins can't? Except highlighting who created the organization, there is not much difference between admin and owner, right? Or is it that only the owner can e.g. delete the organization?

OK, I've experimented and found some differences.

To me, it still is not quite clear what the option "Repository admin can add and remove access for teams" does. I think we should go into more detail here.

I didn't go into more details because I don't know more...! XD

Do you have an idea where I can find information on that topic?

OK, after lots of trials, I think I've managed to understand it. If I'm correct, this is indeed important to detail it in the documentation, because it is not really intuitive and self-explanatory!

File paths are case-sensitive - currently, this does not render with npm run serve. You might want to adjust this path to PNG (or even better, all the other filenames to lowercase).

The style used in Codeberg Documentation is to have filenames kebap-cased

I'd prefer to write the numbers out in this paragraph i.e. 1 -> one

Maybe add (yourself) behind "one team (Owners) with one member"

We might want to highlight that cog in an additional detail screenshot.

We should also describe the difference between "Organization Name" and "Organization Full Name"

Typo persmissions -> permissions

Thinking about it again, it's probably better to not list all the fields of the form in the text again (it's already there, in the screenshot). Something like this might work better:

"The cog next to the organization's name will lead you to the organization's settings, where you can change general settings related to your organization, such as its name, avatar, website or visibility. It is also where you can delete your organization again and access more advanced settings, like organization webhooks."

After that we should explain the difference between "Organization Name" and "Organization Full Name"

Until #83 is resolved, there needs to be a <a name="teams"></a> here, due to the link further down on the page.

Yes, I forgot indeed!

Case-sensitive filenames (see above)

Let's highlight that button in the screenshot

Let's move that paragraph below the screenshot and add an introductory paragraph here instead. Something like:

"On the People tab, you can get an overview of all the people who collaborate in your Organization."

Case-sensitive filenames (see above)

Wording: his/her -> their (sounds a bit more fluent when read out loud, in my opinion).

I would change the second half to ", while Visible makes the avatar of the organization appear in the info card on their profile, as shown in the screenshot below. Note that your membership..."

With a screenshot below :)

Please remove the leading /content from the links, as it otherwise yields Error 404.

Also please add a / before security

This paragraph is a bit long. Maybe we should instead provide an overview of the roles that users can have in an Organization under its own sub-heading, with a few bullet points per role. Maybe, if possible, even as a comparison table.

That suggestion applies to all other places in the document where user permissions are described as well.

If you prefer, we can also leave it like it is now as a baseline and make an overview table at a later point in time.

The table is a very good idea, it will make these permissions more understandable and comparable. I'll try to make something nice.

Is the standard markdown format for tables OK for Codeberg, or are there special details?

Can you recommend a way to add a green tick mark and a red cross in a markdown file, which will be nicely rendered on Codeberg?

Nice to hear that you like the table idea and want to try it :)

I'd recommend to use HTML tables for this, as (at least in my experience) Markdown tables tend to be a bit cumbersome and inflexible to work with.

As for the check mark / cross: In Codeberg Documentation, FontAwesome is used, so it should be possible to write:

<i class="fas fa-check" style="color: green"></i>

for a green check mark and

<i class="fas fa-times" style="color: red"></i>

for a red cross.

I tried that in the md file:

<table>
...
 <tbody>
 <tr>
 <td> Edit/delete organization </td>
 <td> <i class="fas fa-check" style="color: green"></i> </td>
 <td> <i class="fas fa-times" style="color: red"></i> </td>
 <td> <i class="fas fa-times" style="color: red"></i> </td>
 <td> <i class="fas fa-times" style="color: red"></i> </td>
 </tr>
 </tbody>
 ...
</table>

But I don't see any check mark or cross in the preview in VScodium. Is it because VSC doesn't support it or because I do something wrong?

(don't forget it's my first time doing HTML!)

The icons won't show up in VScodium/VSCode because only the final Eleventy render is set up to include FontAwesome. The Markdown preview in your IDE doesn't know about that.

In order to preview how the final page will look like, I strongly recommend to install Node.js and then run

npm install
npm run serve

That way, you'll also get a nice auto-refreshing preview of your articles, without needing to set up anything in addition.

I'm afraid I don't understand this paragraph. What do you mean with "sections of the repositories"?

I suggest to drop that sentence, as it does not really provide much additional information.

I'd write the last sentence a bit differently:

"This is contributing, but not collaborating, since you're still the only one who can *directly* commit changes to your repository."

Please apply the <picture> blocks and webp images in this article too.

And, as you've already written, please remember the filenames :)

I had not done that yet but I had already planed it for the revised version.

I like the overall appearance of the table and I think it really helps clarifying the different levels of permissions within an Organization.

I suggest to sort the permission rows from least to most exclusive and the role columns from most to least privileged, so that the permission ticks form a block/triangle shape, which makes it easier to spot permission differences at first glance.

Example: https://about.gitlab.com/pricing/gitlab-com/feature-comparison/ (although here, the columns are sorted ascendingly).

I can do that, partly at least. I think it makes more sense to group things that belong together (e.g. all the things that repo creators can do). But within the groups and between the groups does make sense indeed.

Yes, let's try it out and see how that looks like 👍

This line probably need a linebreak at its end.

Also, let's link to further up in the text, where "sections" is explained.

Is that the way?

<a href="#sections">sections</a>

with

<a name="sections"></a>

where the link should lead to?

Do I need empty lines before/after?

Yes, that should work.

I don't know for sure if it requires empty lines, but in this case, I don't think so because they're inline elements.

Optionally, you can choose to use Markdown syntax instead of <a href=... for setting the link: [sections](#sections).

I didn't expect that I could mix HTML and Markdown, good to know :)

This should be vertically aligned to the top, to be in line with "Other Teams"

This renders with grey background, but the other even/odd rows do not alternate colors. That's a CSS bug -> #89

(This does not require any changes by you, I wrote this here just for reference)

As far as I can tell, this is not correct:

Once you have read access you can pull from a repository. However, you cannot approve Pull Requests (two entirely different things).
PRs can be approved and merged with Write access to a repository.

I found it weird too, but this is how I understand the text relating to the team options:

"Read = Members can view and clone team repositories.
Write = Members can read and push to team repositories.
Admin = Members can pull and push to team repositories and add collaborators to them."

If my interpretation is wrong (I find yours much more meaningful indeed), then the wording here should be edited. And I can edit the table accordingly of course.

Hmm, "can pull to team repositories" probably means merging pull requests, but that's actually something mere Writers can do too. So, I'm afraid this needs further investigation. Maybe someone who knows more about Gitea's internals can tell us more about this - maybe @ashimokawa or @6543 ? :)

Any news on that?

Neither of the two has answered, but that might just be due to a bug in the mentions system, Codeberg/Community#257

Would it make sense to contact them directly? As far as I can tell, that's the only open issue to finalize this PR (or at least until a second collaborator reviews it)

It might be better to ask a question in Codeberg/Community instead.

Suggested wording: "Edit the repository created by the member" -> "Edit repository settings"

Also, Read and Write collaborators cannot edit repository settings.

That's why the "created by the member" is important: if the owners allow members to create repositories, the member who created the repository is granted admin rights for this repo, i.e. he/she does have the rights to edit repository settings except those in the Danger Zone. This is independent of Read, Write or Admin rights.

I will have to read up on this and get back to you later.

Currently, it seems to me a bit like there's two separate, independent permissions systems, one for organizations (Levels Owner/Team Admin/Team Member) and one for repositories (Levels Owner/Write/Read). If that is the case, it might be good to create two separate tables for each permissions system. Then there wouldn't be ambiguity concerning Read/Write and "member who creates" (= Repository Admin by virtue of being the one who created the repo inside an organization, even if they're not a Team Admin - but again, I'll have to read up on this to be sure).

This is my understanding too.
Having two tables might be the best solution indeed!

But probably not needed if we just mention that creating a repository grants admin rights (see below).

I haven't had the time to verify the assumption above - maybe you want to simply test it on codeberg-test.org instead? There you could create a test organization.

Oh, I did already! And you were right :)

Nice 👍

Wording: See above

In this case, what about "Edit repository settings in the Danger Zone"?

That would be an option too, but "Edit repository settings (including Danger Zone)" would be fine as well. Choose what you like most :)

Wording and Permissions: See above

Admin rights granted to the member who created the repo include adding/removing collaborators to the repo (see above).

These two sentences seem redundant relative to each other.

Yes, kind of. I just wanted to stress that such member will have admin rights and will be listed as collaborator (not just as part of a team).
What about just deleting the last "with administrator rights"?

Yes. Also, if my assumption about the two independent permission systems turns out to be true, it might be enough to say that the member who creates the repository will be a Repository Administrator for the new repository.

Indeed!

With this, there is no need for a second table then, right?

Sorry, this is just a test

The .webp images were not part of the commit, thus this article shows no images.

This is something that could have been easily spotted using npm run serve.

Well, using npm run serve is not so trivial for me: since I'm using my work PC, I have to check with admin to install NodeJS and then try to understand what "run npm install at the root of the source tree" means. When all that is done, I can use npm run serve.

I see, that indeed makes it more complicated. Do I assume correctly that a private PC is not available for this? In that case, if your IT department declines to install Node.js, we'll have to accept that and I'd stop pushing you to use npm run serve 😉

But in case you do get access to Node.js:

The source tree is the directory tree containing all source code - in our case it's basically your copy of this repository.

The root of the source tree is the top-level directory of it, so the one containing the top-level README etc.

And executing a command there means to navigate to that directory, open a command line there (Git Bash or Powershell is fine too) and to then run that command from the command line.

I indeed only have a mac as a private computer. And since I need most of the tools on my work PC already (Git, RStudio...) it makes sense to keep working from that PC too (and installing all that on a mac would also take a lot of time).

But I'll ask IT about it (I guess it's a common theme, but they are always very busy).

And thanks for the instructions (I guess "open a command line there" is a Linux thing, but I just need to adjust the working directory with cd - see I've already learned a lot ;) )!

Let's not use abbreviations. It's better to be explicit than to save a few bytes, in my opinion 😉
Also, that would be consistent with all other article keys in Codeberg/Documentation.

No problem, I'll do it in a minute. My idea was not to save a few keys, but I thought the Key shouldn't be too long.