valueflows

valueflows docs
git clone https://s.sonu.ch/~srfsh/valueflows.git
Log | Files | Refs | README

CONTRIBUTING.md (11496B)

      1 # Contributing to Value Flows
      2 
      3 This project is open commons that anyone can improve.
      4 
      5 We welcome all contributions, such as but not limited to:
      6 
      7 - visual designs
      8 - documentation
      9 - artwork
     10 - use cases
     11 - code
     12 - discussions
     13 - tests
     14 - models
     15 
     16 If you contribute, you'll be invited to join the project members.
     17 
     18 Value Flows aims for autonomous solving of collaborative problems with a common vision.
     19 
     20 ## A suggested workflow
     21 
     22 Our workflow is evolving as we continue to work together and to bring in new people.  So all of this is open to suggestion and discussion.
     23 
     24 We think that a use case driven flow works well for us.  Anyone can create use cases or user stories as a starting point for discussion.  These are best if based on the person's experience, either in software or just in life.  Any textual format is fine, whatever you think communicates.
     25 
     26 An issue can be created for each use case, and people can discuss.  People can propose models (RDF or other) to reflect the use case.  
     27 
     28 Based on the models, we can start to refine the vocabulary.  When it is getting solid, we can write up the .md doc for that subject area so it will get pulled into the main website.  Then continue to refine as needed.
     29 
     30 For new people, looking through the formal gitbook documentation here https://valueflo.ws might be the best way to become familiar with the work done to date.  It also might be useful to look through the [existing use cases](https://lab.allmende.io/valueflows/valueflows/-/tree/master/use-cases).
     31 
     32 We use [Term-centric Semantic Web Vocabulary Annotations](https://www.w3.org/2003/06/sw-vocab-status/note) in following way:
     33 * unstable - included in the vocabulary based on discussions and couple of examples
     34 * testing - exemplified with data snippets based on diverse use cases with variants
     35 * stable - implemented in at least 2 open source applications which work with all included data snippets using that term
     36 
     37 ### Examples
     38 
     39 Helpful examples are published here: https://valueflo.ws/examples/ex-agent.html.
     40 
     41 In terms of our process, we also write example snippets using [JSON-LD](https://json-ld.org/) compatible subset of YAML. Later any implementation of YAML to JSON should be able to convert them and any implementation of JSON-LD parse them.
     42 Examples should include common JSON-LD `@context` we use in examples: `https://git.io/vf-examples-jsonld-context` which we maintain in https://lab.allmende.io/valueflows/support-tools/vf-examples-jsonld-context.
     43 
     44 ## Git process
     45 
     46 Value Flows follows the ["GitHub Flow"](http://scottchacon.com/2011/08/31/github-flow.html) workflow for using [our GitLab repos](https://lab.allmende.io/valueflows):
     47 
     48 * Anything in the master branch is deployable
     49 * To work on something new, create a descriptively named branch off of master (i.e. fairy-princess-use-case)
     50 * Commit to that branch locally and regularly push your work to the same named branch on the server
     51 * When you need feedback or help, or you think the branch is ready for merging, open a pull request
     52 * After someone else has reviewed and signed off on the feature, you can merge it into master
     53 * Once it is merged and pushed to ‘master’, you can and should deploy immediately
     54 
     55 ## Philosophy
     56 
     57 Value Flows aims for simplicity by merging iterative patches that minimally solve [agreed-upon problems](./PRINCIPLES.md).
     58 
     59 > The _Simplicity Oriented Design_, or SOD, process starts with a realization: we do not know what we have to make until after we start making it. Coming up with ideas or large-scale designs isn't just wasteful, it's a direct hindrance to designing the truly accurate solutions. The really juicy problems are hidden like far valleys, and any activity except active scouting creates a fog that hides those distant valleys. You need to keep mobile, pack light, and move fast.
     60 >
     61 > SOD works as follows:
     62 >
     63 > - We collect a set of interesting problems (by looking at how people use technology or other products) and we line these up from simple to complex, looking for and identifying patterns of use.
     64 > - We take the simplest, most dramatic problem and we solve this with a minimal plausible solution, or "patch". Each patch solves exactly a genuine and agreed-upon problem in a brutally minimal fashion.
     65 > - We apply one measure of quality to patches, namely "Can this be done any simpler while still solving the stated problem?" We can measure complexity in terms of concepts and models that the user has to learn or guess in order to use the patch. The fewer, the better. A perfect patch solves a problem with zero learning required by the user.
     66 > - Our product development consists of a patch that solves the problem "we need a proof of concept" and then evolves in an unbroken line to a mature series of products, through hundreds or thousands of patches piled on top of each other.
     67 > - We do not do anything that is not a patch. We enforce this rule with formal processes that demand that every activity or task is tied to a genuine and agreed-upon problem, explicitly enunciated and documented.
     68 > - We build our projects into a supply chain where each project can provide problems to its "suppliers" and receive patches in return. The supply chain creates the "stop mechanism" because when people are impatiently waiting for an answer, we necessarily cut our work short.
     69 > - Individuals are free to work on any projects, and provide patches at any place they feel it's worthwhile. No individuals "own" any project, except to enforce the formal processes. A single project can have many variations, each a collection of different, competing patches.
     70 > - Projects export formal and documented interfaces so that upstream (client) projects are unaware of change happening in supplier projects. Thus multiple supplier projects can compete for client projects, in effect creating a free and competitive market.
     71 > - We tie our supply chain to real users and external clients and we drive the whole process by rapid cycles so that a problem received from outside users can be analyzed, evaluated, and solved with a patch in a few hours.
     72 > - At every moment from the very first patch, our product is shippable. This is essential, because a large proportion of patches will be wrong (10-30%) and only by giving the product to users can we know which patches have become problems that need solving.
     73 > 
     74 > SOD is a hill-climbing algorithm, a reliable way of finding optimal solutions to the most significant problems in an unknown landscape. You don't need to be a genius to use SOD successfully, you just need to be able to see the difference between the fog of activity and the progress towards new real problems.
     75 >
     76 > People have pointed out that hill-climbing algorithms have known limitations. One gets stuck on local peaks, mainly. But this is nonetheless how life itself works: collecting tiny incremental improvements over long periods of time. There is no intelligent designer. We reduce the risk of local peaks by spreading out widely across the landscape, but it is somewhat moot. The limitations aren't optional, they are physical laws. The theory says, this is how innovation really works, so better embrace it and work with it than try to work on the basis of magical thinking.
     77 >
     78 > And in fact once you see all innovation as more or less successful hill-climbing, you realize why some teams and companies and products get stuck in a never-never land of diminishing prospects. They simply don't have the diversity and collective intelligence to find better hills to climb. When Nokia killed their open source projects, they cut their own throat.
     79 >
     80 > A really good designer with a good team can use SOD to build world-class products, rapidly and accurately. To get the most out of SOD the designer has to use the product continuously, from day one, and develop his or her ability to smell out problems such as inconsistency, surprising behavior, and other forms of friction. We naturally overlook many annoyances, but a good designer picks these up and thinks about how to patch them. Design is about removing friction in the use of a product.
     81 >
     82 > In an open source setting, we do this work in public. There's no "let's open the code" moment. Projects that do this are in my view missing the point of open source, which is to engage your users in your exploration, and to build community around the seed of the architecture.
     83 >
     84 > - [How to Design Perfect (Software) Products](http://hintjens.com/blog:19)
     85 
     86 ## Developer's Certificate of Origin 1.0
     87 
     88 By making a contribution to this project, I certify that:
     89 
     90 * (a) The contribution was created in whole or in part by me and I
     91   have the right to submit it under the open source license indicated
     92   in the file; or
     93 * (b) The contribution is based upon previous work that, to the best
     94   of my knowledge, is covered under an appropriate open source license
     95   and I have the right under that license to submit that work with
     96   modifications, whether created in whole or in part by me, under the
     97   same open source license (unless I am permitted to submit under a
     98   different license), as indicated in the file; or
     99 * (c) The contribution was provided directly to me by some other
    100   person who certified (a), (b) or (c) and I have not modified it.
    101 
    102 ## Code of Conduct
    103 
    104 This Code of Conduct is adapted from [Node.js's wonderful
    105 CoC](https://github.com/nodejs/node/blob/master/CONTRIBUTING.md#code-of-conduct).
    106 
    107 * We are committed to providing a friendly, safe and welcoming
    108   environment for all, regardless of gender, sexual orientation,
    109   disability, ethnicity, religion, or similar personal characteristic.
    110 * Please avoid using overtly sexual nicknames or other nicknames that
    111   might detract from a friendly, safe and welcoming environment for
    112   all.
    113 * Please be kind and courteous. There's no need to be mean or rude.
    114 * Respect that people have differences of opinion and that every
    115   design or implementation choice carries a trade-off and numerous
    116   costs. There is seldom a right answer.
    117 * Please keep unstructured critique to a minimum. If you have solid
    118   ideas you want to experiment with, make a fork and see how it works.
    119 * We will exclude you from interaction if you insult, demean or harass
    120   anyone.  That is not welcome behavior. We interpret the term
    121   "harassment" as including the definition in the [Citizen Code of
    122   Conduct](http://citizencodeofconduct.org/); if you have any lack of
    123   clarity about what might be included in that concept, please read
    124   their definition. In particular, we don't tolerate behavior that
    125   excludes people in socially marginalized groups.
    126 * Private harassment is also unacceptable. No matter who you are, if
    127   you feel you have been or are being harassed or made uncomfortable
    128   by a community member, please contact one of the channel ops or any
    129   of the TC members immediately with a capture (log, photo, email) of
    130   the harassment if possible.  Whether you're a regular contributor or
    131   a newcomer, we care about making this community a safe place for you
    132   and we've got your back.
    133 * Likewise any spamming, trolling, flaming, baiting or other
    134   attention-stealing behavior is not welcome.
    135 * Avoid the use of personal pronouns in code comments or
    136   documentation. There is no need to address persons when explaining
    137   code (e.g. "When the developer")
    138 
    139 ## Changes to this arrangement
    140 
    141 This is an experiment and feedback is welcome! This document may also be subject to pull requests or changes by contributors where you believe you have something valuable to add or change.