README.md

   1 Inboxen
   2 =======
   3
   4 [![Documentation Status](https://readthedocs.org/projects/inboxen/badge/?version=latest)](https://inboxen.readthedocs.io/en/latest/?badge=latest)
   5
   6 This is the complete system with everything you need to set up Inboxen.
   7
   8 The current maintainer of this repo is Matt Molyneaux
   9
  10 GPG keys
  11 --------
  12
  13 GPG keys used by Inboxen developers to sign releases:
  14
  15 ```
  16 Matt Molyneaux <moggers87@moggers87.co.uk>
  17     19F5 A8DC C917 FD00 E859   02F4 878B 5A2A 1D47 C084
  18 ```
  19
  20 Security
  21 --------
  22
  23 If you find a security issue with Inboxen, email <security@moggers87.co.uk>. If
  24 you wish to send an encrypted report, then please use key id `0x878B5A2A1D47C084`
  25
  26 Once reported, all security vulnerabilities will be acted on immediately and a
  27 fix with full disclosure will go out to everyone at the same time.
  28
  29 Developing
  30 ----------
  31
  32 You'll need the following tools:
  33
  34 * Git
  35 * Python (we strongly recommend you use virtualenv too)
  36 * PostgreSQL
  37 * NodeJS
  38 * GNU Make
  39 * [EditorConfig](http://editorconfig.org/) *(optional)*
  40
  41 This project comes with a `.editorconfig` file - we recommend installing it to
  42 avoid things like mixing tabs/spaces or accidentally saving files with
  43 DOS-style newlines.
  44
  45 Set yourself up with a virtual environment and run the following:
  46
  47 ```
  48 git clone https:///codeberg.org/Inboxen/Inboxen.git
  49 cd Inboxen
  50 make
  51 ```
  52
  53 When you've made your changes, remember to check your code
  54 style and run unit tests.
  55
  56 Python tests:
  57
  58 ```
  59 python manage.py test
  60 ```
  61
  62 JS tests:
  63
  64 ```
  65 npx grunt karma
  66 ```
  67
  68 To check code style on Python:
  69
  70 ```
  71 tox -e isort,lint
  72 ```
  73
  74 And finally, check JS code style:
  75
  76 ```
  77 npx grunt jshint
  78 ```
  79
  80 ### Local HTTP server
  81
  82 You'll need a `inboxen.config` file, for example:
  83
  84 ```
  85 secret_key: some_random_string
  86 debug: true
  87 tasks:
  88   always_eager: true
  89 ```
  90
  91 If you want to start a local HTTP server to test out your changes, run the following:
  92
  93 ```
  94 python manage.py runserver
  95 ```
  96
  97 You can connect to it on <http://localhost:8000/>.
  98
  99 With `debug=true`, you'll have the Django Debug Toolbar enabled and you can
 100 find the Inboxen styleguide at <http://localhost:8000/styleguide>
 101
 102 ### Pinned Dependencies
 103
 104 Inboxen uses `pip-tools` to help manage its dependencies. The direct
 105 requirements of Inboxen are kept in `requirements.in` and then we use the
 106 following command to pin the entire dependency graph:
 107
 108 ```
 109 pip-compile --upgrade --output-file requirements.txt requirements.in
 110 ```
 111
 112 The resulting `requirements.txt` can be installed to a clean virtualenv with
 113 `pip` to get the exact package versions that Inboxen uses in production. You
 114 can also use the `pip-sync` (which comes with `pip-tools`) to update an
 115 existing virtualenv as well as remove packages that are no longer required.
 116
 117 The same principal applies to `requirements-dev.txt`/`requirements-dev.txt` and
 118 any files found in `extras/requirements`.
 119
 120 If for any reason you wish to bypass pinning dependencies, `requirements.in`
 121 and `requirements-dev.in` are in the format expected by `pip`.
 122
 123 Committing and Branching
 124 ------------------------
 125
 126 ### Branching
 127
 128 All development happens in branches off of `main`. Each branch should have an
 129 associated issue - if there isn't one for what you're working on then create a
 130 new issue first!
 131
 132 Branch names should be of the format `<issue>-<description>` where:
 133
 134 * `<issue>` is the issue you are working on
 135 * `<description>` is a brief description of what's happening on that branch
 136
 137 For example, `129-pin-inboxes` was the branch used for implementing the [pin
 138 inbox feature](https://codeberg.org/Inboxen/Inboxen/issues/129)
 139
 140 Finished branches are then merged into `main`. If there is someone available
 141 to review your branch, your branch should be reviewed and merged by them.
 142 Remember to add a note to CHANGELOG.md when merging!
 143
 144 #### Hotfix branches
 145
 146 Hotfixes should be branched from the latest deploy tag, and then be tagged
 147 themselves as a normal deployment before being merged back into `main`.
 148
 149 ### Commit messages
 150
 151 You should follow the pattern of "summary, gap, details, gap, issue references"
 152
 153 For example:
 154
 155 ```
 156 Blah blah thing
 157
 158 Fixes this thing, changes how we should do something else
 159
 160 fix #345
 161 touch #234
 162 ```
 163
 164 If you are committing on `main`, then make sure to end your commit message
 165 with "IN MAIN" so we know who to blame when stuff breaks.