What do you want from a code respository?
prof_braino
Posts: 4,313
This is a toughie, cause it has restrictions on your reply. These would make me have to stop and think.
What do want from a code repository, as in what do you want it to DO for you? What to you want to achieve?
The restrictions on your answers/requirements/input include:
- You can ask for functions, but you have to describe the function to the extent that we can test if the function is present or not.
"Make it return the name of every code file that contains 'noop'" is testable and verifiable. This would be a candidate.
"Make it better" is NOT verifiable, as it is not quantifiable. This would need to be clarified before it becomes a candidate.
- You can give examples, but you can't dictate HOW it gets done.
"Do X like in SVN, don't do Y like in SVN" are good examples, as these define a particular something.
"Use SVN" is not a good one, it limits the solution to one option (that may or may not have other side effects contrary to our needs)
In other words, what are your High Level requirements for a code repository?
This may or may not be used in the discussions of "how to fix the OBEX, if necessary"; and/or "how to use the Gold Standard repository".
Please include all the simple/obvious stuff, just to ensure we cover it when we get caught up in the details of the less obvious items.
You can also ask or answer "What the heck is a code repository and why would I want such a pain in the ASCII?"
What do want from a code repository, as in what do you want it to DO for you? What to you want to achieve?
The restrictions on your answers/requirements/input include:
- You can ask for functions, but you have to describe the function to the extent that we can test if the function is present or not.
"Make it return the name of every code file that contains 'noop'" is testable and verifiable. This would be a candidate.
"Make it better" is NOT verifiable, as it is not quantifiable. This would need to be clarified before it becomes a candidate.
- You can give examples, but you can't dictate HOW it gets done.
"Do X like in SVN, don't do Y like in SVN" are good examples, as these define a particular something.
"Use SVN" is not a good one, it limits the solution to one option (that may or may not have other side effects contrary to our needs)
In other words, what are your High Level requirements for a code repository?
This may or may not be used in the discussions of "how to fix the OBEX, if necessary"; and/or "how to use the Gold Standard repository".
Please include all the simple/obvious stuff, just to ensure we cover it when we get caught up in the details of the less obvious items.
You can also ask or answer "What the heck is a code repository and why would I want such a pain in the ASCII?"
Comments
Downloadable packages by revision. Again, somebody gets a prop chip, they can go pull, docs, reference code, tool binaries and such. Unpack, install, go on the default, reference setup. If code gets newer than docs, for example, one can see that just by the revision / date meta-data contained in the package name.
It should not be necessary to run source control locally to make effective use of the repository. That's not a recommendation, just something I think needs to be part of the feature set. Actually managing things locally is a great call, and those that do it will get a lot of benefit from it, but not all will do it.
Personally, I would love to associate packages with some threaded meta-discussion about said packages. Context is important. How did it get to the state it's currently in? Where might it be going? Many other similar questions are easily addressed that way.
A review process, particularly if more than code gets in there. When people find some oddity, it should be extremely clear and easy to submit that so maintainers can act on it when it makes sense to do so. Bonus points for a conversion process where somebody reviewing perhaps can elevate to a more inclusive role, should it make sense for them to do so.
States. In a revision controlled system, states are very important. Consider "new" vs "latest released" vs "obsolete" and or maybe "stable"... Somebody can then get answers to things like, "What is the newest, released, stable?" as opposed to "newest" Of course, each state should be defined. IMHO, that's one sentence, maybe two tops.
Clear, documented process and requirements for participation / use. It's my opinion these need to be minimum case and lean, so they aren't a barrier or burden. Think friction free and sticky at the same time. Friction free means they get in, get the value quickly and are off doing their thing. Sticky is that value being high enough to warrant a return and the whole thing being a "center of mass" people build on.
"More than just code" - Very wise folks have told me that code is not much with out tests that show that it works. If we said, "also include your TESTING methods, but it has to be something we can use and not junk you were throwing around while you were hacking", would this be reasonable? Tests require the same love and attention as the code itself, but most folks don't seem to feel this way. Same goes for the whole package: Requirements, functional definition, tests, code, results, and documentation. Even though most folks would not get far with a part without a datasheet, the tendency is to ignore the rest of the package. Would folks really be interested in delivering the work required for solid professional results? (I am, but I'm told I'm kind of nutty that way).
Defining the meta-data: This is no small feat. This requires somebody that knows what this actually means, and somebody (else) to translate it into what the rest of us can understand and use. Do such people exist in our world? I only see them in military and aviation projects, and they aren't let out into the sunshine often .
STATES - we would need to establish what STATES are interesting. Most states are not of particular interest, the only ones we want are the ones that say "I must do something" (to move this forward), or "this is ready" (so I can use it for my project), or "this is not ready" (so I better not use it yet). Even at this simple level, its tricky. Any further detail in this area?
-Phil
I think you are right on your test case statements. Outside of things like aerospace, nobody wants to really do it, unless they have some requirement to do so. Maybe it's enough to include an example of major functionality in the form of the "demo" object. That's a lot of use value without too much labor that might not see a return. The thing is adding constraints like that really only pay off in a greater process. For many people, they just want to know if it works well enough for them to get on with what they are doing...
BTW: I am totally happy to be a test case. I am really interested in seeing "the repository" be successful, and the center of gravity for future things, as I'm a big believer in letting value dictate whether or not something is compelling enough to be authoritative. IMHO, modeling a test case for GOLD objects would be good, so people see them and learn / do from them. Whether or not they do is another discussion. One element of that discussion being it's never GOLD, unless somebody does.
IMHO, modeling a great case helps. If the GOLD stuff were well documented, self-consistent, tested well, etc... that is the "bar" new contributors can reach for. Maybe they don't get there. Maybe they put something in that's close and somebody else finishes it up! That dynamic is why the states and revision control are so important.
Really, I was just thinking about docs and tools. "The repository" should just be where people go to get the reference tools, code, docs, etc... When something new is released, say a revision to the prop manual, or GCC, or Prop Tool, etc... it goes in there as a new revision, the states get changed to reflect it's status, and links elsewhere point to it. That way, it's the single source of truth on these things, and that will create the gravity needed to get people to leverage it and see value from it.
I guess what I am saying is build it so that a professional result can be contained in there. Don't ignore that. Put some professional quality stuff in there too. People like to follow models. If they are pulling from a pro quality repository, they learn about pro quality code, start to do pro quality code, and the bar gets raised. They might put in good code, but not pro code. That's fine. Somebody else can elevate it, or not, depending. Shouldn't matter. Model, don't require and promote would be the simplest way I can say that.
-Phil
The OpenOCD Gerrit Experience presentation describes one implementation of this idea, but it talks more about how that implementation has affected the project and its contributors, than the implementation itself.
Yeah. I don't disagree at all. If nothing happens, I'm quite pleased with what we have now.
I'm not sure what you need from me.
As far as volunteering or not, his is what i said:
"(1) I would be happy to be a contributor as necessary as time permits.
However, I do not want ANY role as (2) a decision maker or (3) a code reviewer."
Let me explain:
(1) Problem: Parallax needs (among many other things being covered here) a simple and generic way to easily import up-to-date code into SimpleIDE or other tools' packages. I have a base-line, but would prefer to use the most up-to-date code without begging for it.
(1) Solution: Pulling a clone of a repository serves the need because it can be automatic. Since that has already been decided by Parallax, I expect the need will be met. All that is necessary is follow through. I await the outcome and will contribute as necessary to help this happen in a passive way. If the end result is reasonable then great (it will be used and hopefully this is the outcome), otherwise it's a waste of time.
(2) Being a decision maker in public or private is usually a thankless and painful job. I've been a manager several times before. The best decisions can make as many enemies as the worst decisions. Accepting a task means finishing it - Mr Phelps.
(3) I'm not interested in subjectively judging other people's work regarding code style or whatever in the repository context. Doing code reviews can be difficult. The worst part though is establishing the code requirements in the first place - you guys do whatever you like with that. I warn though that excessive requirements are counter-productive, can be impossible to meet, and can alienate potential contributors. Succeeding however can give customers confidence.
Finally, I don't mind commenting on mechanics of process because it is more or less objective, and the end result can be tested. By tested I mean by running a script to check and extract information or to successfully build code. If script(s) fail, then things are easily fixed as long as failures are detected in a timely way. Automation can be very helpful.
You've hit upon the key item: subjective judgements vs quantitative evaluation. I'm going to suggest that the process and its evaluations be restricted to items that can be quantitatively evaluated; and subjective evaluation be applied elsewhere, not in the repository nor review processes. We have evidence that subjective evaluations are not universally accepted and cause problems, while quantitative evaluations can be agreed on and (can be made to) achieve the desired result.
We're still drafting the process, thanks in part to your input we might come up with something worth looking at.
The second part of what we'll need from you is that you flag any nonsense you see in the process draft, so we can fix it.
Thanks for this, I'm working on building in something similar to this. I'm not familiar with this particular presentation, but it sounds like it has the effect I'm looking for.
Yes and yes
The main difference is to enable us to track the degree of conformance to a "Gold Standard".
Half the issue is getting a Gold Standard that we can conform to, a method of conforming. The other half is getting a motivation to conform, and a method that does not add burden to what we do already, but rather adds value.
This isn't going to happen quick, but it is fun!
Here we go. I think I'm gong to try to pick your brains off line...
PM sent