On Tue, 2022-08-16 at 12:31 +0200, Jacob Michalskie wrote:
Hi!
A while back, a group of contributors was planning to take care of adapting asknot-ng, a Fedora application powering whatcanidoforfedora.org, for use by the openSUSE Project. That did not happen, so I decided to take it upon myself to get it going. However, I don't know everything that happens within the project, or how much everything within the project works, as much as I would like to, so I need some help with finishing this task.
# How does asknot-ng work?
asknot-ng works by providing a tree of choices, which it then uses to point people in a direction of things to do within a project. The tree is composed of a few layers of categories (as many as required by the branch) which always results in some link the person can follow to learn more about contributing to a certain part of the project.
Just took a look at whatcanidoforfedora.org and I really dislike the way options are presented. The problem is, that you could likely help with more than just one thing the project needs, but the UI/UX makes the guides impossible to properly see and navigate. Have you thought about providing a separate page that just displays all avilable guides in some kind of tree-view (for example a staggered table)?
# How to help out with this task?
If you are a person currently responsible for or know how to contribute to something within the project, we would most likely want to include you in this. There are a lot of ways to contribute, and individually we can't know them all, but all together we can find out ways to reach contributors and for the contributors to reach us.
If you are just a contributor, that has been interested in contributing to a certain part of the project but couldn't figure it out, we would like to hear from you as well. I'm sure we will not get a full coverage from just the contributors here, so your feedback is essential for us to be able to reach out to the right people we might have not considered.
# What are the requirements for inclusion?
As you may be aware, some of the stuff that is developed within the openSUSE Project, or closely associated to the project, has guides helping out the new contributors to be able to contribute to it. In some cases that is CONTRIBUTING.md document in the root of a git repo, in others it's a wiki page like How to contribute to Factory, which is likely pretty well known to anyone that has ever pushed anything to Factory. This kind of documentation is something which we would like to help you develop for your branch of contributions, so that other people can help out in a more meaningful way.
There are plenty of helpful resources for writing good contributing guides on the internet[1], though a lot of them apply to code and not necessarily to other forms of contributions. Remember that any contributor can be a newcomer, and may not necessarily understand things that may be obvious to you, and may want to use your repository as their learning experience. Explaining how things come together is one of the primary things that have to be written down. Ruby on Rails application repository doesn't look like a Ruby on Rails application repository to somebody who has never seen one, and even when using Weblate, it's easy to get lost when you first get started.
For software development, we don't want to link people directly to git repos, because even if they are more familiar with concepts like git, programming languages and have coded before, contribution guides explain how the repo in particular is developed, how to test and run software, and what to consider before creating a pull request.
For other forms of contributions, just linking to a homepage is not exactly helpful, we still want to explain how and why to contribute.
It's really important to include some form of contact (mailing list, matrix, irc) to the maintainers and developers of the project.
Projects not directly under openSUSE, but related to it in significant way (like KDE or GNOME upstreams for example) also count as something we would like to have included.
# I have the guide now, how do I include it?
If you don't want to mess around with editing yaml files, feel free to create an issue on asknot-ng GitHub page[2] or get in contact with us with methods listed below.
If you do want to contribute more directly, there are example yaml files from Fedora side of things already[3], while the openSUSE ones[2] are a little bit empty. The existing content in the openSUSE yaml files is not final, I just wanted to get the website working, so feel free to either add your contribution based on the existing branches, or create a new one. The fact that your project is currently listed doesn't mean it will stay that way then, it may just be a placeholder. If you would like to know our opinion on this before you PR, we have the contact info listed below.
Do not worry too much about images, I will likely be going over them later anyway, and will create whatever ends up being required.
# Where will this be hosted?
Currently the plan is contribute.opensuse.org, I have already submitted an MR to host it on our pinot machine, and it's being reviewed. It will likely come up online in the next couple of days for preview purposes, while we work on adding content.
# How do I get in contact with you?
There are a few ways: * GitHub issues on asknot-ng repo[2] * #web:opensuse.org on matrix * #web on discord.gg/opensuse * web@lists.opensuse.org mailing list * #opensuse-web on libera.chat
[1] https://mozillascience.github.io/working-open-workshop/contributing/ also includes follow up resources
[2] https://github.com/openSUSE/asknot-ng
[3] https://github.com/fedora-infra/asknot-ng/blob/develop/questions/fedora.yml https://github.com/fedora-infra/asknot-ng/tree/develop/questions/includes/fe... LCP [Jake] https://lcp.world/
Regards,
Florian "sp1rit"
--
$\int_\text{now}^{+\infty}\text{Keep trying}$
Matrix: @sp1rit:tchncs.de