search

ethereum / solidity

Solidity, the Smart Contract Programming Language
https://soliditylang.org
GNU General Public License v3.0
23.09k stars 5.72k forks source link

[PROJECT] Provide a "dev" folder #5442

Closed ghost closed 5 years ago

ghost commented 5 years ago

Abstract

Provide a "dev" (development/developer) folder, which contains everything related to "Developing ON Solidity".

Motivation

Specification

The "dev" folder would contain any development related things (relevant to folks which works ON Solidity, irrelevant for folks which works WITH Solidity), like:

Further items would be "CONTRIBUTING.md" and "CODE_OF_CONDUCT.md", but those are expected (by github) in project-root.

Backwards Compatibility

Solidity: none Project: broken history (within the gihub ui) of moved files , see #5440)

leonardoalt commented 5 years ago

I personally think that it makes more sense for these files to be in the root dir. They are relevant for anyone who decides to look into the source code.

ghost commented 5 years ago

change-resistance - always fascinating.

Please feel free to close this issue.

leonardoalt commented 5 years ago

So you simply assumed that I lied about my personal opinion on this matter simply because I am "change-resistant" (another assumption)?

leonardoalt commented 5 years ago

I don't see a reason to close this issue now, as it would be nice to get more opinions.

axic commented 5 years ago

I am actually on the opinion that we should have a high quality contributors chapter in the documentation. The documentation format works well for a lot of things already, why would we need to have a different format for developer documentation as long as it is clearly separated?

ghost commented 5 years ago

So you simply assumed that I lied about my personal opinion on this matter simply because I am "change-resistant" (another assumption)?

???

"change-resistance" is not always consciously.

Then, my comment was of more general nature (was processing several issues in parallel).

"Please feel free to close this issue." - means: this issue does not matter anymore to me (thus: I'm fine if you close it).

This is mainly because the high-severity #5429 was closed), so at this point I give in (kind of: if they don't see the neccessity of #5429, everything else is hopeless/useless).

Want to keep it open, discuss it to death, and have finally again not corrected the main problem?

Go on!

Me out here!

leonardoalt commented 5 years ago

High severity, wow, I wonder how this project survived all this time without a src dir.

ghost commented 5 years ago

... (no comment. My professional pride does not allow me to discuss such totally basic things further)

axic commented 5 years ago

I don't think there is a need to be too much personal from either side here.

@lazaridiscom can you please reflect to my proposal:

I am actually on the opinion that we should have a high quality contributors chapter in the documentation. The documentation format works well for a lot of things already, why would we need to have a different format for developer documentation as long as it is clearly separated?

Do you see something wrong with this?

ghost commented 5 years ago

(am currently on it)

ghost commented 5 years ago

I am actually on the opinion that we should have a high quality contributors chapter in the documentation. The documentation format works well for a lot of things already, why would we need to have a different format for developer documentation as long as it is clearly separated?

Do you see something wrong with this?

There is nothing wrong, its just that if this is to be interpreted/implemented by 10 different persons, they will provide you 10 different results.

e.g., I interpret "Clean Separation" differently than e.g. leonardoalt , I categorize "high quality contributors" differently than e.g. you, I assess the current doc-format differently than you.

What I want is this:

I possibly "sent" myself to a project, executing some task whilst placing myself in a role (e.g. do this coding-taks, fulfill this bounty etc.).

Sample

Fixing the Solidity Project takes around 50 to 100 tiny steps. Problem: nearly each and every step can be "discussed to death". So, it must be performed nearly as a whole, to be efficient, to become visible. I've done several of them to demonstrate how a reworked project would look&feel. Newcomers and high-quality-devs (or high-sensitivity/productivity devs) can judge it best.

(EDIT: to clarify: this does not mean that the existent devs are not high-quality etc.! Its just that they know the project "blindly", so they lost the ability to assess its simplicity.)

Here is the landing-page. From here, visitors are relayed to USER or to DEVELOPER (Solidity itself) documentation:

https://github.com/lazaridiscom/solidity/blob/laz-rework/README.md

I will see to it to apply #5429 and a few more things till Monday, so you can discuss it if you have the time (I somewhere saw that you meet Mondays).

Beside the Structure, there is of course Content (where there real "fighting" starts...). I always strive for the Goal "Zero Docs, as System is Self-Documenting" (never achieved this fully, though...).

(note: this is not the most difficult part of a rework. But if this is not done, then the difficult parts on code-levels are more or less useless)

Benefits / Goals

ghost commented 5 years ago

For the case you didn't notice:

https://github.com/lazaridiscom/solidity/tree/laz-rework

Now throw folks (a mixture of newcomers and high-quality-devs) to the original and the reworked project.

I accept any bets...

chriseth commented 5 years ago

I think we have consent on adding a high quality contributors chapter in the documentation.

ghost commented 5 years ago

You cannot produce high-quality documentation for a low-quality system.

First you have to fix the system.

Ask the folks from zeppelin, if you don't believe me.

https://blog.zeppelin.solutions/solidity-compiler-audit-8cfc0316a420

.

axic commented 5 years ago

You cannot produce high-quality documentation for a low-quality system.

What do you refer to by "low-quality system" ?

Ask the folks from zeppelin, if you don't believe me.

We are in touch Zeppelin, thanks.

ghost commented 5 years ago

I think we have consent on adding a high quality contributors chapter in the documentation. You cannot produce high-quality documentation for a low-quality system. What do you refer to by "low-quality system" ?

The Solidity Project (Code, Structure, Processes).

Just read the Zeppelin Audit. Its unwritten headline is "Solidity Project is quite a Mess - Fix it"

axic commented 5 years ago

I'm not sure I read the same sentiment from there. Though I invite anyone to either explain the reasons properly and provide proper critique or do it better :)

So far no real reasons have been explained, just specific opinions.

leonardoalt commented 5 years ago

This is just your opinion. We've talked to Zeppelin online and in person multiple times and I'm sure what you said is simply not true.

Please stop trolling and being aggressive every time someone disagrees with you. You are not the ultimate source of truth. None of us are.

ghost commented 5 years ago

We've talked to Zeppelin online and in person multiple times and I'm sure what you said is simply not true.

Well, if this is so, then my assessment is that Zeppelin was not worth the $430k budget Zeppelin – $430K. Solidity compiler audit (co-sponsored with Augur)

Please stop trolling and being aggressive every time someone disagrees with you.

no comment

@axic

Well, then, just continue your high-quality work in your high-quality project which produces a high-quality product and high-quality documentation.

Use the high-quality Zeppelin-Audit to strive for HIGHEST quality.

My apologies for ever doubting your quality.

Resting my case.

.

Note to Readers:

leonardoalt commented 5 years ago

Thanks for your assessment. So what you're saying is that if Zeppelin doesn't really mean your "unwritten headline" they're wrong? What a surprise...

I still wonder where you got this "unwritten headline" from. I've read their list multiple times, and the process/structure issues you obsess so much about are mostly in the "low severity" category. Also, in their Conclusion they say Update: All critical and high severity issues were fixed or addressed by the Solidity team.. This seems inconsistent with your completely exaggerated "unwritten headline".

ghost commented 5 years ago

So what you're saying is that if Zeppelin doesn't really mean your "unwritten headline" they're wrong?

Yes, if they don't mean "Your Project is a Mess - Fix it!", then they are totally wrong and not worth their money. (see below for a possible explanation)

and the process/structure issues you obsess so much about are mostly in the "low severity" category.

This is either the major flaw of this Audit, or an "Act of Diplomacy". (again, see below for a possible explanation)

Update: All critical and high severity issues were fixed or addressed by the Solidity team.

See, they got paid, and as professionals, they adapt to their customer (as they should, at least partially).

I still wonder where you got this "unwritten headline" from.

Possible Explanations

Have you ever thought about this possible explanations:

leonardoalt commented 5 years ago

Possible explanations for your opinions? Sure, that could work. Still, assumptions and opinions that you wrongly list as facts.

I am not interested in this discussion anymore and will write no further comments.

ghost commented 5 years ago

then there is no reason to prioritize them higher

Wise folks!

come-maiz commented 5 years ago

Hello, one of Zeppelin devs here. We are happy to clarify anything related to the audit. @lazaridiscom if you have questions, just ping me.

We reported a good bunch of things to fix, but most of them were not high-severity, and none of them are uncommon for a project on the 0.x phase. Some of them are even chosen trade-offs to bootstrap a project. However, note that the Solidity team started to work on the issues as soon as we started conversations, long before we published the results. And they continue improving in all the topics we reported, which has been very encouraging for us because in order to continue building our products at Zeppelin we need to trust that the processes they are building will lead us to an amazing 1.0 Solidity release.

Now, if I may give an opinion nobody asked... :stuck_out_tongue_winking_eye: As a community we have to verify their work, and offer suggestions and hands. That part is awesome. But I think that the disagreement on this discussion became emotionally loaded very quickly, which is understandable but not productive. Note that there is still a long way to go until we reach 1.0, and that there are many many ways to solve the problems we find. Maybe we need to restructure the repo, maybe we can solve this with better docs, maybe we need both; it is hard to know right now, but everything we do is an experiment with small iterations that helps us get closer to the right solution. This project is very demanding so we have an extra role that's to support the people leading it, even when we disagree. As long as they listen and discuss openly, it's very easy to backtrack a little and try the other idea when things aren't going as expected.

An issue is not the right place to discuss this, so sorry for continuing the thread. There is a gitter solidity community channel that sounds like a better place to continue talking.

pura vida.

ghost commented 5 years ago

You sound more like a "diplomat on a pink unicorn" than an auditor. (for the intolerant readers: this was a friendly joke with essence).

It looks like "Zeppelin is part of the problem 'Low Quality of Solidity Project'".

Some comments:

and none of them are uncommon for a project on the 0.x phase

"0.x" on paper. In reality, Solidity is released to production systems, and thus a "1.0" release product.

Solidity drives already millions of real-life dollars. People have bet/invested millions of dollars in Eth/Sol development.

So, you simply owe to all those people to apply the very basic system-design-principles to improve the overall quality.

it is hard to know right now,

It's super-simple to know (just look them up), and super-simple to apply - for experienced folks.

but everything we do is an experiment with small iterations that helps us get closer to the right solution.

In other words: you train yourself via trial/error/delay, instead of getting some more experienced folks to fix the very basic things. And you do this at the cost of your users, providing lower quality than you could.

gitter

Nice toy. But discussing things to death, when the necessary actions are crystal-clear? No thanks!

Note to Readers

Example of an combined "Audit-Rework" (basic-grade/trivial issues are immediately fixed instead of documented, to speed up things)

https://github.com/lazaridiscom/solidity/tree/laz-rework

come-maiz commented 5 years ago

You are being unnecessarily hurtful, and for some strange reason you are assuming that you are more experienced than everybody else here. Your good ideas get lost because of all the noise you are adding. That is not a way to build a development process that we can trust.

Luckily, one of the first things that the Solidity team fixed was to add a code of conduct. That means that you either respect it, or you will have to find yourself a new place to play.

with love, your pink unicorn auditor.

ghost commented 5 years ago

You are being unnecessarily hurtful

I'm just executing an RCA and communicate it openly. Possibly you're just a bit oversensitive.

and for some strange reason you are assuming that you are more experienced than everybody else here.

When I write "experienced folks", it's of general (and not personal) nature. Although it is totally obvious that I outperform you in some(!) disciplines (like you outperform me in others).

Your good ideas get lost because of all the noise you are adding.

Those are not "my good ideas". Those are mostly "System-Design-Principles".

That is not a way to build a development process that we can trust.

Applying System-Design-Principles (and quasi-standard-processes). Nothing to trust, just do it.

Luckily, one of the first things that the Solidity team fixed was to add a code of conduct.

They did not fix this issue. This CoC ( which sadly has polluted github repos) cannot withstand even an relaxed integrity/plausibilliy/validity-check. And its completely redundant for intelligent beings.

And I have a much much better one for you, here an excerpt:

The Pink Unicorn Code of Conduct - Section 4 Paragraphs 3 to 5

Project Maintainers which abuse the Code of Conduct in order to intimidate a Contributor shall be punished by taking away their Pink Unicorn for a minimal period of 4 weeks.

If the abuse happened whilst the Contributor was executing a combined Audit-RCA-Rework, then the Pink Unicorn will be taken away for a minimal period of 4 months.

If the project-maintainer mentioned in this context "hurted feelings" etc., then the Pink Unicorn will be served at the next Sprint meeting (by the professional catering contractor).