readme: update readme, clarify some guidelines and improve example

README.md

@@ -1,8 +1,8 @@
-# Gluon community repository
+# Gluon community packages repository
 
-During the last bimonthly review-day, the Gluon community repository was created. Previously, many attempts to upstream community packages were either stuck for a very long time in the review process or died down completely.
+During one of the bimonthly gluon review-days in 2020, the Gluon community-packages repository was created. Previously, many attempts to upstream community packages were either stuck for a very long time in the review process or died down completely.
 
-We want to solve this by creating a central repository for inter-community packages which is aimed at having shorter review cycles. Ideally, the community repository is maintained by the package maintainers themselves, allowing for faster improvements and a higher willingness for upstreaming community-packages.
+We want to solve this by creating a central repository for inter-community packages, which is aimed at having shorter review cycles. Ideally, the community repository is maintained by the package maintainers themselves, allowing for faster improvements and a higher willingness for upstreaming community-packages.
 
 ## Using this repository
 
@@ -13,41 +13,73 @@ GLUON_SITE_FEEDS='community'
 
 PACKAGES_COMMUNITY_REPO=https://github.com/freifunk-gluon/community-packages.git
 PACKAGES_COMMUNITY_COMMIT=<COMMIT-HASH>
+PACKAGES_COMMUNITY_BRANCH=master
 ```
 
-## Commit guidelines
+Your commit has to be on the branch specified in `PACKAGES_COMMUNITY_BRANCH`.
+If you leave out the `PACKAGES_COMMUNITY_BRANCH`, the repository default branch is used.
+
+You should always test and check changes before using a new commit of the community-packages in your modules, as many people of the community have commit rights and there is currently no test or release process defined.
+
+## Contribution guidelines
+
+In general, everybody is invited to open a pull request (PR), upstream useful packages and contribute to existing ones.
+Everybody who contributed a package is given commit rights for the whole repository - to be able to maintain the package and contribute to the other packages as well.
+
+There is no code ownership.
+Additions to packages of other communities are possible as well, but should adhere to good communication standards
+
+* Use pull requests if you are uncertain about your patches - this is generally a good practice to get feedback from others.
+* Mark pull requests as draft if they are work-in-progress (WIP) or not ready to merge yet
+* Give some time for reviews/feedback for non-urgent issues
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+
+### Style guide
+
+Contributions need to pass `luacheck` and `shellcheck` which is also checked in PRs in the linting pipeline.
+
+If specific adjustments are absolutely necessary (e.g. custom globals for luacheck), add them but make sure that the glob is specific to the files of your package.
+
+### Commit guidelines
 
 * The master branch is protected against the use of `git push --force`.
-* Use Pull Requests if you are uncertain about your patches.
 * Merge commits are disabled in the master branch. If you accept single-commit pull-requests, do a "rebase"- or "squash"-merge instead.
-  This will prevent the commit-history to be cluttered with superfluous "merge" logmessages.
+  This will prevent the commit-history to be cluttered with superfluous "merge" log messages.
+  You can also merge with fast-forward locally and push this commit to the master branch, to keep the same commit hash.
 
-## Commit-message guidelines
+### Commit-message guidelines
 
-Every commit message should prefixed with the package-name, followed by a colon.
+Every commit message should be prefixed with the package-name, followed by a colon.
 
-## Creating a package
+It should also contain a summary of the changes and a short reasoning why they are needed
+
+### Creating a package
 
 For a general documentation on how OpenWrt packages software, see this wiki entry.
 
 https://openwrt.org/docs/guide-developer/packages
 
-Each package has it's own subdirectory in the community-repository.
+Each package has its own subdirectory in the community-packages repository.
 
-### Package naming
+#### Package naming
 
 Ideally, the name consists of the maintaining communities short-handle, followed by the package name.
 
 After this scheme, a community with the short-handle `ffap` would name their package `ffap-sample-package`.
 
-### PKG_LICENSE
+It is also possible to add packages with the `ff` slug to generalize the ownership or add packages without a tying maintenance to a specific community.
+
+#### PKG_LICENSE
 
 The PKG License should be defined as a SPDX ID. See the SPDX FAQ for more details.
 
 [spdx.dev/learn/handling-license-info](https://spdx.dev/learn/handling-license-info/#how)
 
+It is mandatory for packages to include a license in the Makefile
 
-### Sample Makefile
+#### Sample Makefile
 
 See the sample package Makefile below.
 
@@ -59,21 +91,27 @@ PKG_VERSION:=1.0.6
 PKG_RELEASE:=1
 
 PKG_MAINTAINER:=John Doe <[email protected]>
-PKG_LICENSE:=FantasyLicense
+PKG_LICENSE:=GPL-2.0-or-later
 
 include $(TOPDIR)/../package/gluon.mk
 
-define Package/ffXX-hello-world
+define Package/$(PKG_NAME)
   TITLE:=Simple Hello World Makefile
   DEPENDS:=+ffXX-world
 endef
 
-define Package/ffXX-hello-world/description
+define Package/$(PKG_NAME)/description
   A simple package to demonstrate a Makefile for the Gluon
   community-packages repository.
 endef
 
-$(eval $(call BuildPackageGluon,ffXX-hello-world))
+$(eval $(call BuildPackageGluon,$(PKG_NAME)))
 ```
 
-After creating the package, open a pull-request to the community-repository.
+After creating the package, open a PR to the community-packages repository.
+
+#### Package Documentation
+
+You are encouraged to add a README.md in your package folder, which specifies more details about your package.
+
+This is the place to include detailed usage and configuration documentation of your package.