On Wed, 2022-11-30 at 21:59 +0000, PlusNET: Subs wrote:
>
> [ ... list of steps involved in contributing ... ]
>
> a) clone the required code from git://sigrok.org/repository-name to
> local disk (note, not Github)
You can clone from anywhere you want to. Can be sigrok.org, can
be github.com, can be anybody else's repo that you happen to
find. That's the point of git, it's a distributed system (DVCS).
>From the tool's perspective none of the repos is special in any
way. It's just a convention among humans to consider one of them
canonical, which is sigrok.org in this project's case.
All you care about is: Start your contribution from (base it on)
recent master of sigrok.org, i.e. the tip of what the project's
current state of development is. "Falling behind" a little bit
because sigrok's master moves while you are doing your work is
usually not a problem. Only when conflicts arise that recipients
cannot resolve, this will be when you are asked to rebase to
something more recent. But it's rare.
When you depend on sombody else's work, then state it clearly.
Either take "kind of stable" versions of theirs through your
tree, or document that dependency. Though it's also rare that one
contribution strictly depends on another and does not include the
base which they depend on. Because then the contribution would
not be usable as is.
> b) make an host a publicly accessible copy of it (on Github?)
Make it available at any public location. That's the only
requirement. Again, can be github.com, can be repo.or.cz, can be
gitlab or bitbucket or gitea or sourcehut or whatever you happen
to use. Just any public git repo really. (I'd assume wikipedia or
the git homepage to have a list of hosting sites that were known
at a given point in time. Could be incomplete, or could have gone
stale or outdated, but should give you the idea that github is
just one arbitrary hosting provider among others.)
Or could be the mailing list. Though it's rarely done in the
sigrok case, since the list is mostly used for users and their
support requests, sending a patch or a series to the list _is_
one of the options. Fulfills the requirement of "anywhere public,
where others can access it".
Of course you would not send patches or patch series (that is:
lengthy files) to the chat. But you can send URLs there which
reference any public git repo.
See the pattern? Just "make it available to others", that's it.
> c) modify or add to the code as required
> d) commit changes locally
Yes that's normal VCS use. In the case of git or DVCS in general,
you'd do local development, and once you are "kind of done" and
want to publish something, you'd push it to a public place where
others can access it. See above for options.
> e) when ready, submit a pull request
Speaking in most general terms: You "announce" the availability
of what you want to submit. To wherever the project typically
happens to communicate.
This "pull request" approach seems to be some github specific
thing, at least in the form that most users' questions refer to.
The git utility itself has some pull request feature but it's not
what people usually are asking about (see man git-request-pull
for a description), and confuses those who think that github is
the only way of doing something.
So what you do is: Push your locally created, or locally modified
version to somewhere public, and (re-)send the URL to the chat,
or (re-)send the URL or the series to the mailing list, or create
or update some github style pull request, or essentially use any
communication channel that's available.
> f) for the review stage, anyone can go to the relevant Sigrok
> repository* and review the submissions
Any number of people could then learn about the submission's
existence, and respond in any way they feel like. That's again
the point of git, it's a version control system. Not a wiki, not
a bug tracker, not a collaboration suite, not a product lifecycle
management system, not a website creation utility. Just a version
control system, which leaves you the freedom to communicate in
any way that you prefer. Some projects exclusively use mailing
lists, others use github style hosting services, some support
several of these approaches.
Some of the channels may be preferred when multiple are
supported, or the probability of getting feedback could be higher
in some of the channels, depending on their characteristics. But
that's neither new nor specific to the sigrok project.
If you feel that you "must" use github, go and do that. I'm not
stopping you from doing that. Anybody else who feels that github
is great can go there and communicate to you there. My dislike
should be of no concern to anybody else. That'd be strange, the
community is supposed to be larger than that one individual. But
we had this before. Do as you please.
> g) contributor reviews comments and makes changes and the commits -
> we go back interatively to (d) until everyone is happy
Yes that's the iteration through review/feedback cycles. Which
should result in the availability of improved versions of the
submission. Issues get addressed as they get identified and an
approach for them is found. Nothing special again. Normal
software development work.
The "everyone is happy" result would be ideal. You often see
submitters discuss whether they really need to improve their
submission. Or frankly state that they lost interest in the
subject. That's another (not uncommon) way of ending the cycle.
You will also see submitters not being aware of or familiar with
the necessity of improving their submission until it becomes
acceptable. That's when any number of people can help as they
become aware of that situation.
When you push to public git repos, please don't force push.
That'd destroy information which recipients are working with, and
is frowned upon. Provide "parallel"/sibling branches instead as
you push new/different versions of the submission, so that
reviewers can see what has changed between versions, whether
feedback got addressed and how so. Name these branches so that
reviewers can tell them apart. A simple approach is to append
-v1, -v2, etc to their names. Or don't, ignore recipients' needs
and add extra work on them, and see if they want to keep helping
you.
It's OK to append new commits to the end of the current series.
But eventually the series should get reworked so that it can get
taken as is. Also simplifies review when clutter is kept to the
necessary minimum.
> h) at some point developers accept the code, tag it and merge it
> into the project
That is "take it"? Because no tagging is involved in the pick up.
In git terms it's a fetch and (fast forward) merge that is done,
to integrate an external submission into mainline.
Adding unnecessary work at this point to those who take the
submission is a means to decrease their willingness to do it. Not
using git at all, piling up dirty commits and not cleaning them
up, not providing a minimum of essential information, etc etc all
reduces the probability of having the submission taken. But that
shall not be a surprise either.
Need I repeat it? This is my personal perspective as a user of
the sigrok project, matches what I have experienced in other
projects as well, etc etc. If you want the official project's
statement on this, ask somebody who represents the project.
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
