On Tue, 2022-11-15 at 08:03 +0000, Tony Abbey wrote:
>
> I am not a software developer - just a user of Pulseview/Sigrok. So could
> someone please explain how github works - ie merges, forks, approvals etc?
> I have contacts with various high level software people, so maybe I can
> pursaude them to help, if I could understand what needs doing.
Well I'm not a maintainer in the sigrok project, but have been an
active user for a few years. Here is how I see it: It may be
shocking but it's just regular software development and normal
use of git, while none of github is required.
There is no "need" for github at all in the context of the sigrok
project. The project used to work before that, did use git for
version control, did communication with users and between
developers, had bug tracking and continous integration, received
and accepted submissions, etc etc. The github repo was (and still
is) a read only mirror of the code base, mere convenience for
those who think they "must" download from there. Nothing else.
The assumed/perceived/expected "shift" from the sigrok project's
"native" resources and communication channels to github as _the_
place to be I cannot understand. It could be yet another instance
of users agreeing that developers need to do more for them (let's
open yet another communication channel, and also keep watching
there). Or it could be an opportunity which currently is mostly
unused by those who suggested to "also go there".
If you perceive a lack of activity on github, then ask where
those people are who initially suggested or even requested doing
it. There must have been a reason, anyone remembers?
So I cannot speak for how github is done. Maybe github has some
conventions, maybe github users "got trained" to expect something
specific, maybe many github users cannot imagine there'd be a
world outside of that one provider. I don't know, and I don't
care. The sigrok project still has its home at sigrok.org and not
github.com -- unless I missed something. Also doesn't matter
whether other projects have their home on github, or whether
others exclusively work there. None of this dictates to sigrok
how they work. From my perspective github has always just been
a strictly optional alternative view on the code base for the
sigrok project, never an essential utility.
Though I can speak about how git is done and how OpenSource
projects can work, and what I have observed and absorbed from
active participation in the project:
There are communication channels "were the developers are", by
tradition that's IRC and the ML, and these are documented in the
project's code base and on the homepage. You can ask for help
there, or provide help (ideally both of them at the same time,
it's supposed to not be one-way). It's also where you can learn
of what's needed or wanted, and you can consider helping get some
of that done.
When you got code to submit, you'd push it to some public repo
(could be anywhere really, just needs to be public), and mention
the URL either in IRC or the ML. You'd either have the submission
picked up (if it's in a proper shape and desirable), or you'd get
feedback and improve and provide something better. That has
always been the case, there is nothing surprising about it.
The git utility is very helpful in the process. Lets you track
versions, separate concerns in branches, organize commits in
useful chunks, amend your series as you progress, re-spin new
series for review iterations, etc etc. The git utility also lets
everybody use and test what's submitted and has not yet been
taken to mainline. I pity those who sit and keep waiting for
somebody else to ship it completed to their desk so that they can
_start_ seeing it. Many users appear to be stuck in "central
thinking". Which also contributes to stalls when developers want
user feedback while users wait for developers to ship something
that magically works for them. Guess how this works ...
Picking up something into mainline is just a regular git
operation. A developer takes the commits that you published, and
applies them to master, ideally in a linear history for sanity.
(For the interested, it's a rebase then fast forward merge.)
Committing is the boring part and trivial, the effort and essence
is in doing proper reviews and end up with a submission that is
acceptable. This is where the project is severely lacking
manpower, and desperately needs help.
Using github is "just" another alternative. Adds convenience for
those who love web UIs, but also adds confusion (they cannot call
things the same as everybody else does, can they?). Whatever
happens on github is _just_ the communication part of things.
None of github is used and neither required for sigrok work. An
"approval" on github means nothing. No developer uses github's
merge buttons or other utility. No github constraints apply to
whatever sigrok does to accept submissions. No submitter is
forced to use github. All that a sigrok developer cares about is
a given code base and regular git activity to maintain that code
base. Any origin of an acceptable submission is as good as any
other to have it picked up.
So all it takes for a person to participate actively: Engage the
brain (you always should during development work). Pick any tool
you like (a working environment with an editor and git, and some
IRC client or MUA). Pick up public information that's available,
pick up common knowledge as you see it form, and contribute. Help
getting submissions reviewed, and help submitters get their work
into an acceptable shape. Don't wait for a developer to say it
again and again and again and again, consider helping them get
across what was said a hundred times before. Point submitters to
available information if they are not aware. Help them "get git",
don't expect developers to "provide training courses" to each
submitter individually, or even to any submitter several times.
Use feedback from past reviews to help submitters improve their
current submission. This assumes: If you want developers to spend
their time developing the features and fixes that you expect them
to. The alternative is to watch developers having to do this over
and over alone and in addition to their development work. Wear
them out if you wan to. But don't be surprised if this wears them
out.
The current lack of reviewers (active persons helping the project
by helping submitters, not "a title" or badge that you can stick
on) is a consequence of past users watching the developers drown.
It was convenient. For those who watched. But only as long as it
worked. For a special definition of work. This can only be
unbroken by more users lending a hand, to finally get the work
done and not break your developers even more. Sitting by and
watching, shouting from the sides "not enough action, drown
faster!" and "we are bored, entertain us, dance!" is not going to
help in that situation. That's why I so insist to not keep up the
past conditions that took us into this current situation which
everybody is so unhappy with. It's not only that you the users
are frustrated by the deafening silence. Developers are, too.
Think about it!
Consider doing something really helpful. Take a serious look at
what was submitted. Try to walk in the recipients' shoes for a
moment. Would you like to have butchery done to your code base?
Would you enjoy piling up unreadable snippets with unintelligible
comments or commit messages? Do you want warnings in your builds
that haven't been there before? Do you want special hacks that
serve one single person and his very specific local situation and
increase your workload? Or do you want something that works for a
large number of users and remains maintainable? Just apply the
common sense that you also would in any other development task,
wouldn't you?
Remember that the recipient is not receiving a gift, a submission
is a request to accept future work. When a cleanup is too tough a
requirement upon initial submission, what are the odds of the
person to stay around and continue maintenance? There is a reason
why submissions need to be acceptable before they get accepted.
You are not a software developer? Not familiar with hardware and
protocols? But you are a technical person, who understands
constraints and necessities and the concept of technical debt,
aren't you? And consider this: You got a field of expertise, and
think that it is not ubiquitous? Do you seriously expect one or
two developers to intimitely know _all_ of what's covered by the
sigrok project? Every version of every device, every transport,
every file format, every decoder protocol, every programming
language, every build tool, every communication platform, every
pet toy of every user who happens to utter a request, everything
else under the sun? And have the time to care about all of them
equally at the same time? Honestly? Think! Help in whatever way
you can. BUT CEASE WATCHING!
virtually yours
Gerhard Sittig
--
If you don't understand or are scared by any of the above
ask your parents or an adult to help you.
_______________________________________________
sigrok-devel mailing list
sigrok-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/sigrok-devel
