CONTRIBUTING.org
* Contribute to organice
:PROPERTIES:
:CUSTOM_ID: contributing
:END:
First off, thank you for considering contributing to organice. It's
people like you that make organice such a great tool!
** Did you find a bug or do you want to implement a new feature?
:PROPERTIES:
:CUSTOM_ID: did-you-find-a-bug-or-want-to-implement-a-new-feature
:END:
What do we consider a bug? A bug is when an existing feature is
broken.
A feature request is to ask for change in an existing feature or to
ask for a completely new feature.
Hence, if your request is about a feature that Emacs Org mode has, but
organice lacks, this is a feature request, not a bug.
- Ensure the bug or feature was not already reported by searching on
GitHub under [[https://github.com/200ok-ch/organice/issues][Issues]].
- Ensure that the the bug you want to report is not known behavior by
reading the [[file:README.org][readme]] and the [[https://github.com/200ok-ch/organice/wiki][wiki]].
- If you're unable to find an open issue addressing the problem, [[https://github.com/200ok-ch/organice/issues/new][open
a new one]].
- If you want to report a bug or request a feature, please use the
"Bug report" or "Feature request" ticket and fill out the asked
for metadata.
- If your request is neither about a bug nor feature, please do open
a blank issue.
** How we work with issues
:PROPERTIES:
:CUSTOM_ID: how_we_work_with_issues
:END:
One of our quality goals is to keep the amount of issues manageable.
This means that a single person has to be able to groom the backlog
(review the open issues) in a reasonable amount of time.
These are the steps we take to ensure a high quality in the backlog:
1. We only keep issues open on a longer term basis that fulfill one of
the following criteria:
- Someone has committed to work on it or plausibly plans to do so
in the future
- It is a bug or regression
2. If someone files a bug or feature request which is either not clear
to the maintainers or is likely not a bug, but known and documented
behavior, we ask a question or link to the documentation. We also
add a 'question' label to the issue. If the issue creator does not
respond to the question within 5 days, we close the issue. If she
does choose to respond at some point, she can re-open the issue.
If you just want to start a discussion about a new feature or a
different kind of change, but do not plan on working on it yourself,
you are very welcome to join the community chat: #organice on IRC
[[https://libera.chat/][Libera.Chat]], or [[https://matrix.to/#/!DfVpGxoYxpbfAhuimY:matrix.org?via=matrix.org&via=ungleich.ch][#organice:matrix.org]] on Matrix on Matrix. We are
looking forward to seeing you there!
Alternatively, if you really want a change implemented, you can hire
one of the maintainers to do the work. If you want to hire us to
implement a change request, please send us an email to [[mailto:info@200ok.ch][info@200ok.ch]].
** Contributing to the documentation
:PROPERTIES:
:CUSTOM_ID: contributing-to-the-documentation
:END:
The documentation is generated from =README.org= and various other files.
The section on [[#building_docs][building documentation]] explains how it is assembled.
** Development collaboration
:PROPERTIES:
:CUSTOM_ID: development-collaboration
:END:
We have good quality assurance and an established workflow. This is it:
1. Open a new GitHub pull request
2. In the form of a User Story (As =<persona>=, [When I =<state>= ], I
want =<something>=, so that =<measurable achievement>=
3. Ensure the PR description clearly describes the problem and
solution. Include the relevant issue number if applicable.
4. New Branch in Git
5. Naming: =(feature|fix|chore)/issue-id/short-description=
6. If your PR includes a substantial change to the overall
architecture, consider writing an [[https://organice.200ok.ch/documentation.html#adr-001][architecture decision record]].
7. Develop / Test locally until tests pass
- We use [[https://github.com/prettier/prettier-eslint][prettier-eslint]] to format code, which combines both
~prettier~ and ~eslint --fix~ for the best of both worlds. This
repository includes ~.prettierrc.json~ and ~.eslintrc.yml~ with
some configuration options that Prettier will use automatically.
- Run ~yarn prettier-eslint --write~ to automatically format the
whole codebase, or ~yarn prettier-eslint --list-different~ to see
which files don't currently match the repository's style.
- If you're using Emacs, you can autoformat your source files:
https://github.com/munen/emacs.d/#auto-formatting
- Please use ~eslint~ to ensure that your changes conform with
our linting rules. You can run ~yarn eslint~ to check for rule
violations, and also ~yarn nibble~ to tackle them one category
at a time.
- ~yarn lint~ will run both sets of linters.
8. Create Pull Request on Github to =master=
- Check that the tests also pass on CI
9. Core Team: Merge to =master=, deploy and accept the Issue on
Github
*** Definition of Done
:PROPERTIES:
:CUSTOM_ID: definition-of-done
:END:
An issue is done when:
- Functionality has been implemented
- Functionality has been verified
- Surrounding main functionality has been regression tested
- Code has been reviewed
- Proper code style
- Code has tests (acceptance tests for user visible changes,
otherwise at least unit tests)
- Follows clean code guidelines and architecture best practices
- Code has been documented
- Code has been merged
- Tested on supported browsers
*Clean code guidelines*
- Create small and highly cohesive modules
- Avoid long modules and classes
- Extract modules to separate responsibilities
- Create small methods or functions
- Avoid long methods or functions
- Extract methods or functions to separate responsibilities
- Do one thing
Thanks!🙏🙇
organice Team
[[https://200ok.ch][200ok llc]] and all [[https://github.com/200ok-ch/organice/graphs/contributors][contributors]]