search

ortiza5 / modding-vivaldi

A not-even-WIP-anymore collection of guides about modifying the Vivaldi browser
The Unlicense
7 stars 1 forks source link

Update contributing guidelines #1

Closed ghost closed 3 years ago

ghost commented 3 years ago

Please discuss below what to change in CONTRIBUTING.md. The current content is just so that we don’t have to create everything from scratch. I have set the rules rather strict so that we can relieve them if needed; I think not everyone would suggest tightening them even if they wanted to.

Welcome are not only suggestions to the meaening, but also to the style or language used.

ghost commented 3 years ago

I would like to receive a comment from @ortiza5, @luetage and @LonMcGregor. If you don’t care about this project, just let me know about it.

@code3z and @sjudenim and maybe others like @Zalext and @Pathduck might also be interested. I won’t require a comment from you, but I will give you approximately a week to respond (if you say you aren’t interested, it will help reduce these one-week delays).

I consider the “I don’t care” comments for the whole project; if you only don’t care about this PR, express it clearly.

code3z commented 3 years ago

@tiosgz Is this supposed to replace the repo of @ortiza5? Why are you organizing this, I thought you left V? Do you want someone else to take it over later?

In terms of contributing, I think the original outline/structure can be closed, then have an "everyone can contribute policy" (no guarantee of your contributions being accepted, though).

I also think you should add a liscense.

ghost commented 3 years ago

Is this supposed to replace the repo of @ortiza5?

Basically yes.

Why are you organizing this, I thought you left V?

Because nobody else seems to be able to organise it or is active enough. I don’t use the browser actively, but as you can see I am still active in the community.

Do you want someone else to take it over later?

That may or may not happen 🤷

In terms of contributing, I think the original outline/structure can be closed, then have an "everyone can contribute policy" (no guarantee of your contributions being accepted, though).

See https://github.com/tiosgz/modding-vivaldi/blob/9d60271720dd8ddc9d0f54aba72ae4df7219449e/CONTRIBUTING.md#L28-L32

I also think you should add a liscense

See #2.

ortiza5 commented 3 years ago

@code3z see discussion starting here.

@tiosgz These are good guidelines. No problems from me.

Unfortunately, I am feeling a bit burnt out with this project for the moment, but I could potentially be more involved in the future. You can make me down as an "I don't care" for now, and I will let you know if/when I am ready to be more involved.

One guide I could help with is a more advanced guide for using mutation observers to deal with issues around fullscreen/minimal-ui and the mail bar.

ghost commented 3 years ago

Oh, cool. You can actually approve the PR hundred times if two isn’t enough for you :-P

Unfortunately, I am feeling a bit burnt out with this project for the moment, but I could potentially be more involved in the future. You can make me down as an "I don't care" for now, and I will let you know if/when I am ready to be more involved.

So it turns out that the most active person has the least energy?

But I should finally stop criticising you, since you agreed to do things together instead of each on their own. As you can see in the changes from ca2cddb, there are other ways to help than only writing the guides. Also, the ones currently present on the forum can maybe be migrated with less effort. (We will have to do something with them anyway – ask the authors to deprecate them?)

One guide I could help with is a more advanced guide for using mutation observers to deal with issues around fullscreen/minimal-ui and the mail bar.

Great 👍 That also means that you have some time to prepare for it, since there’s no point in having it before the basics.

ortiza5 commented 3 years ago

Oh, cool. You can actually approve the PR hundred times if two isn’t enough for you :-P

Accidental, sorry.

So it turns out that the most active person has the least energy?

Since this is just a hobby, it doesn't make sense to do it if it isn't something you enjoy doing. I have enough projects to work on, so a project that I have lost motivation to contribute to isn't something I am going to force myself to do.

Hopefully some time will let me view this project differently.

Sorry 🤷‍♀️

ghost commented 3 years ago

Since this is just a hobby, it doesn't make sense to do it if it isn't something you enjoy doing. I have enough projects to work on, so a project that I have lost motivation to contribute to isn't something I am going to force myself to do.

Are you saying that now? Okay, I will just try to keep it alive.

Zalext commented 3 years ago

I would like to receive a comment from @ortiza5, @luetage and @LonMcGregor. If you don’t care about this project, just let me know about it.

@code3z and @sjudenim and maybe others like @Zalext and @Pathduck might also be interested. I won’t require a comment from you, but I will give you approximately a week to respond (if you say you aren’t interested, it will help reduce these one-week delays).

I consider the “I don’t care” comments for the whole project; if you only don’t care about this PR, express it clearly.

I'm here :)

code3z commented 3 years ago

@Zalext Welcome! Do you have any modding experience?

ghost commented 3 years ago

I'm here

Does that mean that you like the contributing guidelines as they are, or do you want them to change?

LonMcGregor commented 3 years ago

I'm kind of busy with a lot of other stuff at the moment, so I probably won't be able to help with this little project for a while.

luetage commented 3 years ago

Well, this went south quickly. I want to discuss some basic things. First of all, what’s the goal of this project? So far I can see two things. The contributing guidelines seem to point towards the goal of streamlining mods and there will or won’t be an effort to teach people coding Javascript.

I have said before that I find it questionable to force modders to format their code in a specific style. It’s an entry barrier and will make it harder for people to contribute. It’s also not nice to have to tell people “no”, because they didn’t use the right amount of spaces or forgot to set a semicolon. The engine in the back doesn’t care about it, the important thing is whether it runs. We also add additional steps and force modders to abide by our rules.

About teaching people Javascript… There are a myriad of learning tools, articles, videos and helpful sites on the web, which combined do a better job than anything we could achieve. If people are too lazy to inform themselves, they shouldn’t be messing with application files in the first place. It’s a harsh opinion, but I think it’s true. The existing guides already inform people how to get mods running, automate this process and how to inspect the UI. All things specific to Vivaldi; and all of these will help people, who can already code, become productive quickly. I would say it only makes sense to discuss, explain topics, which are specific to Vivaldi, like the use of APIs. But these are very advanced topics and the premise of the whole idea was to help out beginners. So what is it now?

We should also be aware the Vivaldi team discourages Javascript mods and we are in a somewhat indeterminable situation because of this. Unlike CSS mods, which enjoy basic support, Javascript mods will run on every application profile. You have to manually disable them to report bugs, switching profile is not enough. Making it easier for beginners to install mods, will make the devs work potentially harder. The funny thing is adding basic support for js mods, would somewhat protect them from that.

Anyway, as I’m babbling on here. In my opinion the goal should be to make mods easier to discover and to provide options to tame the chaos of the forum board, not to wrestle control of mods away from the authors. For this purpose I would suggest setting up an article on this github, explaining and suggesting a way to tag mods on the forum, suggest to modders to manage and collect their mods either with Github/GitLab/&c., or alternatively by creating a personal, dedicated topic on the forum, where they list all their mods and link to them. Both github/lab accounts and topics can then be linked to from a central place, creating an index. This way users will have the opportunity to search mods by author and tagging the specific topics will enable users to search for specified mods, such as projects concerning the address bar, only CSS solutions &c. What makes sense and how this should be presented in the end we can work out right here, where everyone who wants to provide input gets a voice. Well, that’s my suggestion at least. As for advanced guides, Github is of course a perfect place to write and collaborate on guides and to present them, may that be through a wiki or readme or whatever. Doesn’t seem like anyone wants to start one though, at the moment.

ghost commented 3 years ago

Well, this went south quickly.

Indeed. I did realise this in the morning, but failed to admit it to myself.

First of all, what’s the goal of this project?

I must admit that even I don’t exactly know it. I think it was meant to organise the efforts of @ortiza5 & @code3z so that the result is worth at least something. Now that @ortiza5 is not interested in doing it anymore, & @code3z doesn’t seem to be able to actually write anything, it’s just another reposotory to be deleted.

Yeah, I’m just another unorganised bloke it seems. Also yes, the existing guides on the forum already cover most topics. This even didn’t have to be a repository on GitHub if I didn’t mention the possibility in https://forum.vivaldi.net/post/473286, then @ortiza5 weren’t so quick at creating one, & then me being already lost didn’t create this one (but OTOH if this is going to become something, git+GH allow more control than the forum – which I’ve already written in the linked forum post).

Probably I wanted this to be more thorough, but that isn’t very likely to happen.

I have said before that I find it questionable to force modders to format their code in a specific style.

I didn’t plan this repo to contain mods, at least not any soon. And it makes sense to me that guides & similar which are in one repository are consistent with their formatting.

About teaching people Javascript…

I didn’t expect more than a few links in this direction.

The existing guides already inform people how to get mods running, automate this process and how to inspect the UI. All things specific to Vivaldi; and all of these will help people, who can already code, become productive quickly.

(See earlier.)

We should also be aware the Vivaldi team discourages Javascript mods and we are in a somewhat indeterminable situation because of this. Unlike CSS mods, which enjoy basic support, Javascript mods will run on every application profile. You have to manually disable them to report bugs, switching profile is not enough. Making it easier for beginners to install mods, will make the devs work potentially harder. The funny thing is adding basic support for js mods, would somewhat protect them from that.

Well, at the point when someone is in modding, this probably doesn’t matter too much.

Anyway, as I’m babbling on here. In my opinion the goal should be to make mods easier to discover and to provide options to tame the chaos of the forum board, not to wrestle control of mods away from the authors. For this purpose I would suggest setting up an article on this github, explaining and suggesting a way to tag mods on the forum, suggest to modders to manage and collect their mods either with Github/GitLab/&c., or alternatively by creating a personal, dedicated topic on the forum, where they list all their mods and link to them. Both github/lab accounts and topics can then be linked to from a central place, creating an index. This way users will have the opportunity to search mods by author and tagging the specific topics will enable users to search for specified mods, such as projects concerning the address bar, only CSS solutions &c.

Good idea, but in such a case I’d need to take at least partial control over my mods before I get into it.

What makes sense and how this should be presented in the end we can work out right here, where everyone who wants to provide input gets a voice. Well, that’s my suggestion at least.

I’ll keep this repo as is until this discussion ends. If it turns out there’s no reason to keep it, I’m ready to delete it (another repo to emerge & die quickly, yay). If we decide to use it for something (& we decide to use this repo), it’s almost empty, thus ready to serve that purpose.

As for advanced guides, Github is of course a perfect place to write and collaborate on guides and to present them, may that be through a wiki or readme or whatever. Doesn’t seem like anyone wants to start one though, at the moment

I was getting ready to start as soon as this PR is merged (i.e. the guidelines are clear). (Note the past tense.)

code3z commented 3 years ago

@LonMcGregor That’s okay. It’s not all going to happen in one day or even one month, maybe you could contribute something later if you have time as I know you have a lot of modding knowledge. I will probably add your basic structure to the guide as it would be helpful for new modders.

@luetage We won’t teach people JS, but there are many many things specific to modding that are not covered in the guide. We may teach people some JS features or styling that are helpful for modding.

code3z commented 3 years ago

Purpose: To allow people who already know CSS or JavaScript to be able to create and share mods for the Vivaldi Web Browser.

Contributing: I am happy with the guidelines as they are.

Zalext commented 3 years ago

Hi,

Then, would be good to start with the basics and enumerate the different articles? Like a Content's Guide

For example:

As mentioned, How to Tag.

So, The Dev's Guide would have:

Comments/Description | Tagging | Index |

Comments/Description

A Template

Despite each one preference:

Tagging

The need steps

Index of own Mods

As mentioned and other suggestions

code3z commented 3 years ago

@Zalext Im not completely sure what you mean.

the guide is not just how to share but how to create. For instance, inspecting with devtools, debugging, testing, special ()(); functions, waiting for elements timers, and the technical details (react, VivaldiHooks)

Zalext commented 3 years ago

@Zalext Im not completely sure what you mean.

the guide is not just how to share but how to create. For instance, inspecting with devtools, debugging, testing, special ()(); functions, waiting for elements timers, and the technical details (react, VivaldiHooks)

Is to make a list about what is expected to be added.

After the list is done and approved then add the info for each item.

code3z commented 3 years ago

Yes, that's what I was thinking as well. there is an outline.md in my fork of the project. https://github.com/code3z/modding-vivaldi/blob/master/outline.md

ghost commented 3 years ago

Please do not discuss concrete instances of content; as soon as the general purpose is decided, you can use issues for that.

code3z commented 3 years ago

@tiosgz Okay. What do you think the general purpose is? Teaching people java script is definitely not going to happen.

ghost commented 3 years ago

What do you think the general purpose is?

The point is that at the moment there’s none. Don’t want everything immediately, that’s not how the world works.

code3z commented 3 years ago

Don’t want everything immediately, that’s not how the world works.

Aw, really?

@tiosgz Should the guidelines have required information to be submitted in the comments on pull requests? I was thinking asking people to include forum username, and certain information about what the pull request does.

ghost commented 3 years ago

There’s no need for it. The PR title should always be descriptive enough, & I don’t see why we’d need forum usernames on GitHub.

ghost commented 3 years ago

I am still unsure about if all this makes sense, but would like to find something meaningful this repository can be used for. I give my opinions below, & would be happy if someone gave theirs as well.

The ideas presented so far (±half of them taken from @luetage’s comment), of which I would like to choose one (or more) if any at all makes sense, are these. If you have some other, it is welcome.

Zalext commented 3 years ago

I saw the New Modding Guides as to:

That like an index.

Maybe there's something else.

--

About list of Mods it would be done later. I've been looking at older Mods, some seems no more working, but I don't know enough to be sure. Those would be closed or leave it, by the Moderators.

But those old still working but burried would be bumped and on this flow, would be added to list.

This just as a plus when checking old but new Mods to apply.

Sine seems a though work, and active Mods are mostly on first pages, I consider that has not much urgency to do that list, or at least get it ready right now.

ortiza5 commented 3 years ago
  • modding guides
    • good if they are thorough, but if they are the same as those on the forum, I don’t see anything but duplication of effort

The current pinned guides are far from comprehensive. There are certainly some posts around with the information, but a compilation seems like a worthwhile endeavor.

  • guides on how to make mods easier to find
    • seems like too little for a full g/GH repo

As for "making mods easier to find", this could be a single guide about best practices for mod posting ( e.g. preview image, tags, description, etc. )

These are what I think should be the focus for now. The other aspects can be looked into later as @Zalext said.

And yes, I will be involved. Don't want this project to die on account of my lack of participation.

ghost commented 3 years ago

And yes, I will be involved. Don't want this project to die on account of my lack of participation

I didn’t want to say anything like that – but of course you are welcome.

code3z commented 3 years ago

There’s no need for it. The PR title should always be descriptive enough, & I don’t see why we’d need forum usernames on GitHub.

@tiosgz there could be certain things you want every PR title or description to have, or maybe use labels instead. I see multiple uses for forum usernames:

  • modding guides

    • good if they are thorough, but if they are the same as those on the forum, I don’t see anything but duplication of effort

Yes

  • guides on how to make mods easier to find

    • seems like too little for a full g/GH repo

Definitely

  • collection of mods

    • too much effort, plus it would need everyone to participate

  • collection of links to mods, with some UI or something that would make it searchable

    • a lot of effort, but it doesn’t necessarily require everyone to cowork on this

If we are successful in showing people how to make their mods easier to find, this will be unnecessary. Perhaps there could be links to mods that are great for learning from and/or important for Vivaldi, but not a full directory. The forum will be the directory. The only thing left would be making them easier to install, but that's out of scope for this project. I may be able to work on that if I have some free time.

I think we could start organizing the project soon. Here was my basic outline:

# Outline File

## CSS
- Welcome (1)

- Getting started with DevTools (2A)

- Exporting and adding your mods (3)

- Modding tips and wrap up (4)

- Sharing your mods (8)

## JS
- Welcome (1)

- Getting Started with devtools (2B)

- The structure of a JS mod (5)

- Practice Mod (6)

- Tips and wrap up. (7)

- Sharing your mods (8)

"Sharing your mods" includes best practices for posting mods, so that should cover "making them easier to find"

The other thing to consider is making the headers machine-readable like adblock.

[tiosgz edit: fixed formatting]

ghost commented 3 years ago

(I am still waiting if someone else posts their opinions about the goal of this repo, that’s why I don’t react to any of yours yet.)

There’s no need for it. The PR title should always be descriptive enough, & I don’t see why we’d need forum usernames on GitHub.

there could be certain things you want every PR title or description to have, or maybe use labels instead. I see multiple uses for forum usernames:

  • Post about this guide on the forum, and thank contributors
  • Ask someone for help even if you don't have a GitHub account
  • Know who made the pull request even if you have never heard of their GitHub username.
  • The forum usernames are shorter and many Vivaldi users know other users by their forum usernames, not the GitHub ones.

I’m starting to see how it could be useful, but IMO it’s better to include the authors at the top of each guide instead of the PR. People are not very likely to dig through the file history & find the relevant PR, while scrolling the page a bit is nothing hard.

  • modding guides

    • good if they are thorough, but if they are the same as those on the forum, I don’t see anything but duplication of effort

Yes

  • guides on how to make mods easier to find

    • seems like too little for a full g/GH repo

Definitely

I suppose these are reactions on the possibilities, not my opinions, right?

ghost commented 3 years ago

I guess everyone had enough time. We all want modding guides as originally, great!

Can you two please once again look at all the rules in CONTRIBUTING.md & check that you really want them all? (I have already realised that the 80-char limit makes enough sense only for text/markdown documents, not code.)

@ortiza5, can you please also comment on #2? (If my comment there isn’t clear, I am for the Unlicense as well.)

ortiza5 commented 3 years ago

In the Markdown section, I suggest that this line should include images as well:

  • separate lists, block quotes, code blocks, headings, separators and similar from other content with a blank line on each side,

Images suffer from the same cramped look that the other mentioned elements mentioned experience. There are probably some exceptions to this, but in general images look better with added whitespace when included in-between text.

Otherwise, I don't see any glaring issues. I am a fan of longer code char limits, but it is a matter of preference (I normally go with 120).

code3z commented 3 years ago

@tiosgz I think the underscore for italic asterisk for bold thing is unnecessary. Also I think you should add the thing about forum usernames. And the American English thing is not necessary. I would like to hear your reasoning for the dark mode thing. And must we use semicolons? (I’m kidding, I’ll use them)

You’ve written quite a bit, not all of which should be taken out, but the most important things need to be highlighted or something.

ghost commented 3 years ago

I think the underscore for italic asterisk for bold thing is unnecessary.

That’s for consistency. If you have a good reason against, I might remove it though.

Also I think you should add the thing about forum usernames.

Done.

And the American English thing is not necessary.

It mainly targets words like ‘colour’ vs ‘color’ etc. Quotes & dashes for consistency again.

I would like to hear your reasoning for the dark mode thing.

There’s a big chance someone will be viewing the guides with dark mode (esp. given that GH supports it OOTB). While dark images in light pages don’t usually do any harm, light images in dark pages are quite aggressive.

You’ve written quite a bit, not all of which should be taken out, but the most important things need to be highlighted or something

I’m bad at this kind of things & I don’t think there’s an important information surrounded by less important information anywhere (I don’t want to just bolden all text in one section etc).

Zalext commented 3 years ago

Hi,

Will the GH Guide be pointed from VForum Guide? Or will be pasted to the VForum in each respect Guide?

If will be pasted, Which I suppose is the more reliable.

To use the asterisk will be better for italic, otherwise to change it before will be needed: https://commonmark.org/help/

If on GH is better and will be done once, then, ok.

Thank you

ghost commented 3 years ago

I imagined that we would only link the repository in our signatures; at most create a thread for questions.

Anyway, every MarkDown flavour (including CommonMark) should support both underscores & asterisks, so that’s not a problem.

code3z commented 3 years ago

I imagined that we would only link the repository in our signatures; at most create a thread for questions.

Yes, a topic would be good, but the content should be on GitHub.

@tiosgz I see your points but I think you have overcomplicated things a bit. Could you make one section “Suggestions” and one “Requirements”?

ghost commented 3 years ago

Could you make one section “Suggestions” and one “Requirements”?

I have tried to differentiate them with the words I used (‘prefer’, ‘try’ → you might not need to give a reason for not following it; (nothing) → you must have a good reason; etc).

code3z commented 3 years ago

How would you feel about changing all suggestions to using the “prefer” wording and bumping the requirements to the top?

ghost commented 3 years ago

I’m not so sure about using ‘prefer’ everywhere, but I’ll try to sort every list by importance instead of trying to categorise it. Thanks for the suggestion!

ghost commented 3 years ago

It should be sorted by priority now. I have also changed some wording & one or two rules, so please recheck it again (sorry about this).

code3z commented 3 years ago

At this point it looks good to me.

ortiza5 commented 3 years ago

My review still stands. Unless you want me to review it again 😜

ghost commented 3 years ago

Thanks both! (But also everyone who commented)