| 1 | Project Scope |
| 2 | ------------- |
| 3 | |
| 4 | * Bug fixes and maintenance |
| 5 | * Prioritize extensibility and simplicity |
| 6 | * Do not make the codebase more complex, keep it simple to hack on |
| 7 | * Do not add extra dependency (if we do, add compile time switch to disable it) |
| 8 | * New features may be added if it cannot be achieved (easily) via a shell script, |
| 9 | doesn't break backwards compatibility and doesn't violate any of the above rules. |
| 10 | |
| 11 | Note: Since we aim to be a drop-in replacement for sxiv, we intend to keep all |
| 12 | sxiv's behaviors/features even in cases where removing them would make the |
| 13 | code-base simpler. |
| 14 | |
| 15 | Also note that (n)sxiv uses `imlib2` for loading images. Thus any request or |
| 16 | patches for adding support for new image formats should go into |
| 17 | [imlib2's repo](https://git.enlightenment.org/old/legacy-imlib2) instead. |
| 18 | |
| 19 | |
| 20 | Contribution Guideline |
| 21 | ---------------------- |
| 22 | |
| 23 | When contributing, make sure: |
| 24 | |
| 25 | * Your contribution falls under nsxiv's scope and aim |
| 26 | * You follow the existing code style (see the "Code Style" section below) |
| 27 | * You open the pull request from a new branch, not from master |
| 28 | * To avoid using force pushes, especially for bigger patches. Only use them |
| 29 | when there's merge conflicts. |
| 30 | |
| 31 | If your contribution is not suitable for general use, it will not be included in nsxiv. |
| 32 | For changes that are very much up to preference, such as changing values in config.h, |
| 33 | please do not open a pull request unless you have an objective explanation. |
| 34 | |
| 35 | See the [open issues](https://codeberg.org/nsxiv/nsxiv/issues) to find something |
| 36 | to work on. You can also filter the issues via label: |
| 37 | |
| 38 | * [Good first issue](https://codeberg.org/nsxiv/nsxiv/issues?labels=49698): |
| 39 | (Easy) Issues which do not require much if any experience. |
| 40 | * [Up for grabs](https://codeberg.org/nsxiv/nsxiv/issues?labels=49705): |
| 41 | (Intermediate) Issues which are free for anyone who wants to pick it up. |
| 42 | Might require some experience. |
| 43 | * [Help wanted](https://codeberg.org/nsxiv/nsxiv/issues?labels=49699): |
| 44 | (Intermediate/Experienced) Issues where we require some help. |
| 45 | |
| 46 | |
| 47 | Code Style |
| 48 | ---------- |
| 49 | |
| 50 | `nsxiv` mostly follows the [suckless code-style][sl], with a few exceptions. |
| 51 | If your editor supports [.editorconfig](../.editorconfig) then you'll already be |
| 52 | off to a good start without needing much manual intervention. Additionally we |
| 53 | provide a [clang-format](./.clang-format) configuration for reference, which you |
| 54 | may use via [`git-clang-format`][cf] to format the changes you've made (please |
| 55 | do not run it globally on the entire code-base since clang-format gets a decent |
| 56 | amount of edge cases wrong). |
| 57 | |
| 58 | [sl]: https://suckless.org/coding_style/ |
| 59 | [cf]: https://clang.llvm.org/docs/ClangFormat.html#git-integration |
| 60 | |
| 61 | |
| 62 | Development workflow for maintainers |
| 63 | ------------------------------------ |
| 64 | |
| 65 | If we notice you contributing and/or showing interest in issues/pull requests, |
| 66 | we may invite you to join the nsxiv org as a member. Being a member simply means |
| 67 | you will be able to approve, disapprove and merge pull requests. |
| 68 | |
| 69 | Our workflow regarding pull requests is the following: |
| 70 | |
| 71 | * Code related changes require two approvals, but documentation related |
| 72 | changes (e.g. typo) can be merged with just one. |
| 73 | * If a pull request has a single approval, no objections and has been open |
| 74 | for more than 7 days, then it may be force-merged. |
| 75 | * Always prefer squashing when merging. In the case a PR makes more than one |
| 76 | significant change, use the "don't squash" tag and rebase instead. |
| 77 | * When merging, make sure the commit message is cleaned up properly so that |
| 78 | it reflects the current intention of the PR. |
| 79 | |
| 80 | For releases, the process is the following: |
| 81 | |
| 82 | * Tag the release with a "vN" tag, where N is the version number. Also set |
| 83 | the commit message and tag description for the release commit to "Release |
| 84 | version N". Make sure to use an annotated tag. |
| 85 | * Update `VERSION` macro in `config.mk`. |
| 86 | * Update the changelog (`etc/CHANGELOG.md`): |
| 87 | * Include link to the release tarball and add the release date. |
| 88 | * Document only the changes or fixes between releases. Don't document |
| 89 | changes which never made it into a release. |
| 90 | * Use the "Changes" section to document behavior changes since the last |
| 91 | release, the "Added" section for new features, and the "Fixes" section |
| 92 | for fixed bugs or regressions. |
| 93 | * Include pull request IDs with reference style links. |
| 94 | |
| 95 | Mirroring to GitHub: |
| 96 | |
| 97 | Assuming `origin` is the name of the codeberg remote and `github` is the name |
| 98 | of the github remote; run the following commands to mirror the codeberg repo to |
| 99 | github: |
| 100 | |
| 101 | ```console |
| 102 | $ git fetch --prune origin |
| 103 | $ git push --prune github '+refs/remotes/origin/*:refs/heads/*' '+refs/tags/*:refs/tags/*' |
| 104 | ``` |
| 105 | |
| 106 | The first command updates the local repo and the second command pushes |
| 107 | everything on `origin` without pushing any of the local branches. |
| 108 | |
| 109 | - - - |
| 110 | |
| 111 | For mundane development related talks which don't warrant their own issue, use |
| 112 | the [general discussion](https://codeberg.org/nsxiv/nsxiv/issues/294) thread. |