fix the basic - CONTRIBUTING.md

[Tido]

Hi,

 

UPDATE  26 of May 2018: minor text for better reading, Document section added tools, repository idea

 

  SITUATION:
In our "day to day" exchange on Armbian we are probably to close to look at it the way it looks for a firsttime visitor. Many members of the community have seen that as well and wrote about it in the Forum - but they didn't come up with a solution.
Now, neither do I have a solution nor do I have nice document, but I think we need to set some standard pillars of FOSS projects in order to overcome some of our well known problems.

For the ones who joined armbian a while ago (me for example May 2015) have read about missing developers, rare drive-by contributions. Which is sad because as a FOSS (Free and Open Source Software) project there is no sustainability without contributors.
We (armbian members) cannot explain that ourselves, tens of thousand of people have SBCs and use armbian, we are friendly - why so little participation?

 

  IDEA:
I will not call a CONTRIBUTING.md the 'holy grail', but certainly a clear idea and a process attracts more people than "We do this when we feel like" == no information about how we treat and like contributions.

In the documentation we have a https://docs.armbian.com/Process_Contribute/ is this enough, is this the right place?
The development happens on GitHub so I think this is also the place where CONTRIBUTING.md information belongs and we can link from the documentation to this place, to write it down just once.

 

  DOCUMENT:
Contributing Guidelines
Oftentimes open source projects place a CONTRIBUTING file in the root directory. It explains how a participant should do things like format code, test fixes, and submit patches.

  an example:

Contributing

When contributing to this repository, please first discuss the change you wish to make via issue, email, or any other method with the owners of this repository before making a change.

 

Our tools to control and setup armbian
armhwinfo
armbiansetuphw
armbianzram
armbian-config
armbianmonitor
scripts
configuration

 

Repository structure

- The "wip" (work in progress) branch 

or  a branch per SoC/big change
- dev-rockchip  |  dev-sunxi (Allwinner)  |  dev-meson64 (AMLogic)

- Incremental kernel patches can be applied to "master" (also known as Stable) after testing (eg. a little .deb for testers) since they should only ever break one family, and should be fairly consistent across all members.

 

 

Pull Request Process

    Update the README.md or Documentation with details of changes to the interface, this includes new environment variables, exposed ports, useful file locations and other parameters.
    Increase the version numbers in any examples files and the README.md to the new version that this Pull Request would represent. The versioning scheme we use is SemVer.
    You may merge the Pull Request in once you have the sign-off of two other developers, or if you do not have permission to do that, you may request the second reviewer to merge it for you.

 

License
    This project is under GNU GENERAL PUBLIC LICENSE Version 2, June 1991 - Copyright (C) 1989, 1991 Free Software Foundation, Inc., <http://fsf.org/>

 

 

What does belong into the Armbian-CONTRIBUTING.md? - please just leave a comment of what is important to you - so I can collect and put it together for us

 

---

That's all I have for now, I will update this OP as anything important changes/comes up.

 

Edited May 26, 2018 by Tido
see on top

[lanefu]

Wrangling new dialog regarding branching under this thread.    Original from a tangent on the tritium h3 thread I will paraphrase:

 

@tkaiser  Random Dev branches aren't helping anything..  It trashed me work -- I'm going to jump.... for real this time.

 

@Tido Things will continue come apart until we suck it up and document a process and live with it

 

@chwe Perhaps a different directory structure with more segmentation for board or platform can keep branching simple

 

@TonyMac32  How about a few branches for the top 3-ish common architectures and we make sure things are re-based prior to merging

 

@Igor Play nice

 

@lanefu  Anybody heard of git flow?

 

 

 

 

 

 

[lanefu]

So for serious.... if master was locked down to just like Igor and whatever deputized player he sees, it could truly be used to reflect whatever the official stable release of armbian is out there...... Occasional hotfixes could be cherry picked in, otherwise it's left alone until the next release.

 

RC's would allow for feature freezes while debugging prior to release.

 

Everybody else works out of the development branch.... and by work I mean they use feature branches which are rebased to development prior to merge request.

 

To eliminate confusion or overlapping,   Following issues closely would help.

[chwe]

that's up to more serious code contributors to decide... I'll adjust my small contributions to whatever way they prefer. But I think before we let grow the development branch with more .csc/wip boards we should decide how we solve this in the future.

[lanefu]

12 minutes ago, chwe said:

that's up to more serious code contributors to decide... I'll adjust my small contributions to whatever way they prefer. But I think before we let grow the development branch with more .csc/wip boards we should decide how we solve this in the future.

 

 

Right so let me stab at delineation between supported, WIP, and CSC. 

• Supported - Board has a documented maintainer listed in the board config file or elsewhere... (Documented maintainer could be "armbian core team" woudlnt have to 1 person, but would have to some sort of consensus
• WIP -  A board with a documented maintainer in config file that is intended to be "supported", but legitimately is a work in progress.
• CSC - A board with contributions, but no documented maintainer.  Use at own risk.   No image builds... or maybe nightlys, at best.    If code is clearly atrophying, and doesn't seem to have any popularity,  Core armbian maintainers (lords of master branch) purge at will.
  
  As a general rule of them board related commits should not have any code impacting the build system overall and merge requests would be rejected.  
  
  Naturally a CSC board could get promoted into a WIP and ultimately a supported board, but that can be up to the Armbian core developers. 

 

[lanefu]

I also nominate Igor as benevolent dictator, and Zador and Tkaiser as the other members of core development team.    A group of 3 is easy to vote when hard choices come up or there's unclear vision, and there's no such thing as a split decisions.

 

 

[TonyMac32]

:'(

[lanefu]

25 minutes ago, TonyMac32 said:

:'(

 

Sorry. Hmm does that mean I wasn't helpful or blabbering too much?

[TonyMac32]

Hahaha no, I was excluded from "The list".  Only a joke, and there has been some quite loud opposition to naming a "king of the project" or an "inner circle". 

 

Personally I think a lot of this comes down to not wanting to assume the complexity of a larger project, but the project has decided it won't wait for that complexity and is now demanding it.  We're at the point where Armbian gets mentioned in kernel mailing lists about various SoC's, so our ability to address issues is becoming quite public.

 

I only push the branches because if someone makes a stupid branch we can kill the branch, and changes won't be wound around anything else that may be useful causing a horrific mess.  

 

[Tido]

I like a lot what you guys brought up over night. Some of it is already written somewhere in the forum/website/documentation, but it needs to get into meaningful stream, so I will try to reflect what I read in the 1. post in this thread.

- For example stable branch, just as an example (and needs a fix for github)

 

6 hours ago, lanefu said:

if master was  "locked down",  it could truly be used to reflect whatever the official stable release of armbian is out there...... Occasional hotfixes could be cherry picked in, otherwise it's left alone until the next release. 

 

ReleaseClients  would allow for feature freezes while debugging prior to release.

 

Everybody else works out of the development branch.... and by work I mean they use feature branches which are rebased to development prior to merge request.

 

To eliminate confusion or overlapping,   Following issues closely would help.

To me as an advocate of  STABLE  this sounds great, reflects the idea of @TonyMac32 if I understand you correct.

 

 

Quote

some frustration having its roots in the current way of 'improvement'.

it is not only about size and complexity, it is also about having fun to develop armbian - that leads to some necessary improvement | a new concept  and discipline. As already said a community of 3 is easy, more than that need some easy to follow guidelines.

 

What I want to say, the  CONTRIBUTING.md  should tell a lot, but shouldn't be to long, from my perspecitve.

 

Last but not least, I am happy that after all (I started this thread in March, the idea I had much earlier)  that I receive some comments here - because it is not about me, but us

---

 

5 hours ago, lanefu said:

Right so let me stab at delineation between supported, WIP, and CSC.

I guess this belongs to documenation and Website (on the download FAQ we explain that as well - I like your description)

 

[lanefu]

7 hours ago, TonyMac32 said:

Hahaha no, I was excluded from "The list".  Only a joke, and there has been some quite loud opposition to naming a "king of the project" or an "inner circle". 

 

And @TonyMac32 nominates @TonyMac32  lol.

 

I appreciate the idealism around not having an executive or inner circle, but I think that's something best suited for when the project was smaller or when it levels up to the next level of maturity and there's enough committed maintainers for individual components.      Even if there is an inner-circle, it's still self-organizing and not some evil scenario.

 

IMHO, In Armbian's current state, having a small set of individuals to help make quick decisions when needed and continually articulating a clear vision/mission for the project is critical for maintaining momentum.    I do want to emphasize the continually articulating vision/mission.   Repetition minimizes confusion.

 

7 hours ago, TonyMac32 said:

Personally I think a lot of this comes down to not wanting to assume the complexity of a larger project, but the project has decided it won't wait for that complexity and is now demanding it.  We're at the point where Armbian gets mentioned in kernel mailing lists about various SoC's, so our ability to address issues is becoming quite public.

 

Well said.  

 

7 hours ago, TonyMac32 said:

I only push the branches because if someone makes a stupid branch we can kill the branch, and changes won't be wound around anything else that may be useful causing a horrific mess.  

 

 

I really do like the idea of branches for some of the core architectures, but I think for it to be successful, the branches would need dedicated maintainers, curators and are keep them healthy and in sync with development.    It lines up nicely with what things could look like in the next level maturity state that I touched on above., but I think there's probably an intermediate step of living closer minimalist gitflow process that may need to occur first.

[TonyMac32]

There are two types of development branches: permanent and temporary.  For a permanent one yes, curating is a necessity and "naming names" is needed.  For something more specific (changing kernels, adding a driver, targeting a new u-boot, etc), a branch for that change could be made, tested, reviewed, flattened and committed into master, and the branch removed.  The owner of that branch is the creator of that branch.

[lanefu]

Okay I see what you're driving at now!

 

Work that's being done, which impacts a subsystem rather than a component (ex: all sunxi vs a single board) should be done overtly.  The best way to make that overt is to have a feature branch visible in the main Armbian repo.   

 

....As opposed to someone working from a fork and then just surprising the world with a pull request.    Standard contributions can (and should) of course come from forks and pull requests.