Skip to content

Commit

Permalink
Fix docs for 2.x (#1949)
Browse files Browse the repository at this point in the history 
* overhaul docs for 2.x

* remove outdated docs

* fix warnings and minor improvements

* move howto to wiki

* move howto to wiki

* move the calender up

* add link to 3x readthedocs migration
  • Loading branch information
@s-martin
s-martin committed Mar 12, 2023
1 parent 29edd74 commit 927520c
Show file tree
Hide file tree
Showing 10 changed files with 273 additions and 729 deletions.
11 changes: 2 additions & 9 deletions CODE_OF_CONDUCT.md
View file
Original file line number Diff line number Diff line change
@@ -1,14 +1,7 @@

Dear Phonieboxians,

As the Phoniebox community is growing, somebody suggested a pull request with the below document. I was hesitant to include it right away, but at the same time I thought: it might be good to have some kind of document to formulate the foundation this project is built on. To tell you the truth, this document is not it. However, it is a start and I thought: why not open this in the spirit of open source, sharing and pull requests and see if and how you or you or you want to change or add parts of this very *standard and corporate* document. Like most of you, I also have a small kid and my time is scarce, I might find some time though to add a bit.

All the best, Micz

2018-08-21

# Contributor Covenant Code of Conduct

> 📝**NOTE:** Dear Phonieboxians, as the Phoniebox community is growing, somebody suggested a pull request with the below document. I was hesitant to include it right away, but at the same time I thought: it might be good to have some kind of document to formulate the foundation this project is built on. To tell you the truth, this document is not it. However, it is a start and I thought: why not open this in the spirit of open source, sharing and pull requests and see if and how you or you or you want to change or add parts of this very *standard and corporate* document. Like most of you, I also have a small kid and my time is scarce, I might find some time though to add a bit. **All the best, Micz**, 2018-08-21
This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at [http://contributor-covenant.org/version/1/4][version]

## Our Pledge
Expand Down
110 changes: 49 additions & 61 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -1,49 +1,16 @@
# Contributing

# Table of contents
> 📝**NOTE:** This describes contributing for **version 2.x**. For Version 3 please see <https://github.com/MiczFlor/RPi-Jukebox-RFID/blob/future3/develop/CONTRIBUTING.md>
* Naming conventions
* Structure of files and folders
* How to contribute

# Naming conventions

* **Files & folder names**
* all **lower case**
* separate words with **dashes** `-` (less keystrokes, better autocomplete recognition, in HTML links dashes can not be confused) not camel/PascalCaps or underscores
* be **descriptive** in your wording (e.g. `raspberry`, not `juicy-red-thing`)
* move **from general to specific** (e.g. `food-fruit-raspberry`, not `raspberry-food-fruit`)
* unique and clear product IDs (e.g. MAX7219)
* the product ID should be written as is (no lowercase)
* the product ID should come last in a descriptive name (e.g. dot-matrix-module-MAX7219)
* be consistent and look at existing examples before you invent something new

* **`README.md`**
* written in capital letters, so it's easier to spot
* every new folder of a component deserves a `README.md` file

# Structure of files and folders

Inside the root folder or the repo, these folders are important:

* `scripts`
* this folder should contain **only actively used scripts** (controlling playout, rfid tiggers, etc.)
* some possible services and features might live in the *components* directory (see below)
* if one or more scripts are needed for the activation of a component (like daemons), they should be copied to the `scripts` directory during installation / activation
* WHY? By copying, changes will NOT affect the github repo and make it easier for users to modify their components
* `components`
* contains sub- und subsubfolders for additional features, services, hardware
* **subfolders** are for categories (e.g. displays, soundcards) and are plural, even if there is only one
* **subsubfolders** are specific hardware, services, features, protocols, etc.

# How to contribute
## How to contribute

Contributors have played a bigger role over time to keep Phoniebox on the edge of innovation :)

We want to keep it as easy as possible to contribute changes that get things working in your environment. There are a few guidelines that we need contributors to follow so that we can have a chance of keeping on top of things.

Development is done on the git branch `develop`. How to move to that branch, see below.

## Getting Started
### Getting Started

* Make sure you have a [GitHub account](https://github.com/signup/free).
* Open an issue if one does not already exist.
Expand All @@ -62,19 +29,21 @@ git pull

The preferred way of code contributions are [pull requests (follow this link for a small howto)](https://www.digitalocean.com/community/tutorials/how-to-create-a-pull-request-on-github). And ideally pull requests using the "running code" on the `develop` branch of your Phoniebox. Alternatively, feel free to post tweaks, suggestions and snippets in the ["issues" section](https://github.com/MiczFlor/RPi-Jukebox-RFID/issues).

## Making Changes
Please check also our [Code of Conduct](CODE_OF_CONDUCT.md).

### Making Changes

* Create a topic branch from where you want to base your work.
* This is usually the master branch.
* Only target release branches if you are certain your fix must be on that
* This is usually the `develop` branch.
* Only target release branches (i.e. `master`) if you are certain your fix must be on that
branch.
* To quickly create a topic branch based on master, run `git checkout -b
fix/master/my_contribution master`. Please avoid working directly on the
`master` branch.
* Make commits of logical and atomic units.
* Check for unnecessary whitespace with `git diff --check` before committing.

~~~
~~~bash
Added shuffle mode and RFID controls for it (issue #130) #140

Adds a shuffle mode for MPD to be triggered by RFID card.
Expand All @@ -91,7 +60,7 @@ The preferred way of code contributions are [pull requests (follow this link for
master branch.
~~~

## Making Trivial Changes
### Making Trivial Changes

For changes of a trivial nature, it is not always necessary to create a new issue.
In this case, it is appropriate to start the first line of a
Expand All @@ -102,39 +71,58 @@ For commits that address trivial repository maintenance tasks or packaging
issues, start the first line of the commit with `(maint)` or `(packaging)`,
respectively.

## Submitting Changes
### Submitting Changes

* Push your changes to a topic branch in your fork of the repository.
* Submit a pull request to the repository.
* The core team looks at Pull Requests on a regular basis.
* After feedback has been given we expect responses within two weeks. After two
weeks we may close the pull request if it isn't showing any activity.
* After feedback has been given we expect responses within two weeks. After two weeks we may close the pull request if it isn't showing any activity.
## Revert Policy
### Revert Policy
By running tests in advance and by engaging with peer review for prospective
changes, your contributions have a high probability of becoming long lived
parts of the the project. After being merged, the code will run through a
series of testings. These Tests can reveal incompatibilities that are difficult
to detect in advance.
By running tests in advance and by engaging with peer review for prospective changes, your contributions have a high probability of becoming long lived parts of the the project. After being merged, the code will run through a series of testings. These Tests can reveal incompatibilities that are difficult to detect in advance.
If the code change results in a test failure, we will make our best effort to
correct the error. If a fix cannot be determined and committed within 24 hours
of its discovery, the commit(s) responsible *may* be reverted, at the
discretion of the committer and Phonie maintainers.
The original contributor will be notified of the revert.
If the code change results in a test failure, we will make our best effort to correct the error. If a fix cannot be determined and committed within 24 hours of its discovery, the commit(s) responsible *may* be reverted, at the discretion of the committer and Phonie maintainers. The original contributor will be notified of the revert.
### Summary
#### Summary
* Changes resulting in test failures will be reverted if they cannot
be resolved within one business day.
* Changes resulting in test failures will be reverted if they cannot be resolved within one business day.
## Guidelines
### Guidelines
* Currently Phoniebox runs on Raspian **Buster** . Therefore all Python code should work with **Python 3.7**.
* For GPIO all code should work with **RPi.GPIO**. gpiozero is currently not intended to use.
## Additional Resources
### Additional Resources
* [General GitHub documentation](https://help.github.com/)
* [GitHub pull request documentation](https://help.github.com/articles/creating-a-pull-request/)
## Naming conventions
* **Files & folder names**
* all **lower case**
* separate words with **dashes** `-` (less keystrokes, better autocomplete recognition, in HTML links dashes can not be confused) not camel/PascalCaps or underscores
* be **descriptive** in your wording (e.g. `raspberry`, not `juicy-red-thing`)
* move **from general to specific** (e.g. `food-fruit-raspberry`, not `raspberry-food-fruit`)
* unique and clear product IDs (e.g. MAX7219)
* the product ID should be written as is (no lowercase)
* the product ID should come last in a descriptive name (e.g. dot-matrix-module-MAX7219)
* be consistent and look at existing examples before you invent something new
* **`README.md`**
* written in capital letters, so it's easier to spot
* every new folder of a component deserves a `README.md` file

## Structure of files and folders

Inside the root folder or the repo, these folders are important:

* `scripts`
* this folder should contain **only actively used scripts** (controlling playout, rfid tiggers, etc.)
* some possible services and features might live in the *components* directory (see below)
* if one or more scripts are needed for the activation of a component (like daemons), they should be copied to the `scripts` directory during installation / activation
* WHY? By copying, changes will NOT affect the github repo and make it easier for users to modify their components
* `components`
* contains sub- und subsubfolders for additional features, services, hardware
* **subfolders** are for categories (e.g. displays, soundcards) and are plural, even if there is only one
* **subsubfolders** are specific hardware, services, features, protocols, etc.
51 changes: 0 additions & 51 deletions INSTALL
View file

This file was deleted.

Loading

0 comments on commit 927520c

Please sign in to comment.