Contributor FAQ #92

Merged
lhinderberger merged 8 commits from :contributor-faq into master 2 years ago

This is my draft of the contributor FAQ for Codeberg Documentation, ready for review.

I'm looking forward to your comments and additions :)

Closes #69 #80 and possibly #52

This is my draft of the contributor FAQ for Codeberg Documentation, ready for review. I'm looking forward to your comments and additions :) Closes #69 #80 and possibly #52
lhinderberger added the
Status: Ready for Review
Kind: Documentation
labels 2 years ago

I will try to have a look this week.
But you'll have to explain me how to add comments like you did for my PRs!

I will try to have a look this week. But you'll have to explain me how to add comments like you did for my PRs!
n requested changes 2 years ago
<a name="file-naming-conventions">
### How should files be named?
Please adhere to [Kebap-Case](https://en.wikipedia.org/wiki/Letter_case#Special_case_styles) naming rules for any files in Codeberg Documentation.
n commented 2 years ago
Collaborator

Typo: Kebap-Case --> Kebab-Case

Typo: Kebap-Case --> Kebab-Case
n commented 2 years ago
Collaborator

Also might want to change the link to https://en.wikipedia.org/wiki/Kebab_case in case it gets its own article in the future.

Also might want to change the link to https://en.wikipedia.org/wiki/Kebab_case in case it gets its own article in the future.
Poster

Thanks, good catch! I fixed it :)

Thanks, good catch! I fixed it :)
lhinderberger marked this conversation as resolved
and PNG formats (webP and JPEG for photographs), they should be in a large enough resolution so that text is clearly
readable and their filenames should follow Codeberg Documentation's [naming conventions](#file-naming-conventions).
Please put screenshots under `assets/images/[section]/[article]/...` where `[section]` and `[article]` are the kebap-cased names of the section or your article, respectively.
n commented 2 years ago
Collaborator

Same here (kebab-case).

Same here (kebab-case).
lhinderberger marked this conversation as resolved
n commented 2 years ago
Collaborator

Perhaps screenshot requests for occasional contributors could also be documented as part of #75.

Edit: and Knut too :)

Perhaps screenshot requests for occasional contributors could also be documented as part of #75. Edit: and Knut too :)
Poster

@n - Will do, as soon as #75 is ready 😉

Depending on how quick #75 can be resolved, it might be worth putting that change in another PR though.

@n - Will do, as soon as #75 is ready :wink: Depending on how quick #75 can be resolved, it might be worth putting that change in another PR though.
ivan-paleo reviewed 2 years ago
ivan-paleo left a comment

Great article; I have only few very minor comments!

Great article; I have only few very minor comments!
To contribute to Codeberg Documentation, the first thing you should do (if you haven't already done it) is to create your own fork of the [Codeberg/Documentation repository](https://codeberg.org/Codeberg/Documentation).
Then, for each major contribution that you want to make (e.g. for each new article), create a new branch, make your contributions and finally make a Pull Request to the Codeberg/Documentation repository. You can find the source code to all articles in the `content` directory of Codeberg
Documentation's source tree.

Is there a line break here (there shouldn't be one)?

Is there a line break here (there shouldn't be one)?
Poster

Where exactly do you mean?

Where exactly do you mean?

between "Codeberg" and "Documentation" (lines 15-16)

between "Codeberg" and "Documentation" (lines 15-16)
Poster

Good catch! I fixed it. By the way, simple line breaks like these have no effect on Markdown rendering, as far as I can tell. So that's why it was easy to miss.

Good catch! I fixed it. By the way, simple line breaks like these have no effect on Markdown rendering, as far as I can tell. So that's why it was easy to miss.
lhinderberger marked this conversation as resolved
Every section and article has a unique `key`. If `parent` is set to the `key` of another section, the current article will become a child of that other section.
The other fields are `title` and `order`, where `title` is merely a display name and determines the menu entry label as well as the article's heading but has no other "technical" semantics and `order` is a number that can be used to enforce a specific order of articles (which is good for step-by-step guides such as Getting Started for example).

That sentence is very long. I suggest to split it into two or even three sentences.

That sentence is very long. I suggest to split it into two or even three sentences.
Poster

I've now split it up into a list.

I've now split it up into a list.
lhinderberger marked this conversation as resolved
> Please do not repeat the article's title as a first-level heading in Markdown. It will added automatically when generating the final site.
### Can I preview my article?
Yes, but currently only if you're working with a local clone of the repository. In that case, simply follow the instructions in the `README.md` file to set up and run a local preview.

Would it make sense to add a link to the README.md file?

Would it make sense to add a link to the README.md file?
Poster

Yes :) -> Done

Yes :) -> Done
lhinderberger marked this conversation as resolved
Poster

Thank you @ivan-paleo for your comments - I have modified everything accordingly!

What do you all think, are we ready to merge? :)

Thank you @ivan-paleo for your comments - I have modified everything accordingly! What do you all think, are we ready to merge? :)
lhinderberger added
Status: Review
and removed
Status: Ready for Review
labels 2 years ago
lhinderberger added the
Status: In progress
label 2 years ago
lhinderberger changed title from Contributor FAQ to WIP: Contributor FAQ 2 years ago
lhinderberger changed title from WIP: Contributor FAQ to Contributor FAQ 2 years ago
Poster

Okay, I've added instructions about example repositories and screenshots using the "knut" account/organization. Please have a look if everything's correct and feel free to merge :)

Okay, I've added instructions about example repositories and screenshots using the "knut" account/organization. Please have a look if everything's correct and feel free to merge :)
lhinderberger removed the
Status: In progress
label 2 years ago

Okay, I've added instructions about example repositories and screenshots using the "knut" account/organization. Please have a look if everything's correct and feel free to merge :)

It looks all good to me.

> Okay, I've added instructions about example repositories and screenshots using the "knut" account/organization. Please have a look if everything's correct and feel free to merge :) It looks all good to me.
lhinderberger requested review from n 2 years ago
Poster

Hey @n, are the "knut" instructions okay and can this be merged? :)

Hey @n, are the "knut" instructions okay and can this be merged? :)
n requested changes 2 years ago
n left a comment
Collaborator

Looks good to me except for a small error :)

Looks good to me except for a small error :)
- For changes that are critical, e.g. ones that might legally affect Codeberg e.V., the chairperson of Codeberg e.V. will need to approve of the changes as well
### Where to create example repositories?
Please create example repositories for the Documentation in the `knut` organization on `codeberg-test.org`.
n commented 2 years ago
Collaborator

This should be on Codeberg production, right?

This should be on Codeberg production, right?
Poster

Absolutely right! Thanks for spotting this 👍

Absolutely right! Thanks for spotting this 👍
lhinderberger marked this conversation as resolved
Poster

With the last error resolved, this is now ready to merge, which I will do right away, along with #82 :)

With the last error resolved, this is now ready to merge, which I will do right away, along with #82 :)
lhinderberger merged commit 41e5355441 into master 2 years ago
lhinderberger deleted branch contributor-faq 2 years ago
n approved these changes 2 years ago

Reviewers

n approved these changes 2 years ago
The pull request has been merged as 41e5355441.
Sign in to join this conversation.
No reviewers
No Milestone
No Assignees
3 Participants
Notifications
Due Date

No due date set.

Dependencies

This pull request currently doesn't have any dependencies.

Loading…
There is no content yet.