Improve the Contributor/Developer Experience

[jon-nfc]

Contributors / Developers are arguably the most important persona when it comes to the Software Development Life Cycle (SDLC). Even more so than the end-user.

Note

Even though this ticket is for us to improve the Contributor / Developer experience, please feel free to comment on this ticket. This includes any difficulties you have found or areas you'd like improved / clarified.

Details

As there can be many levels of experience, making it clear regardless of this level of experience the workflow and dev requirements will be crucial.

Our intent has always been to use the CONTRIBUTING.md as the first point of contact for contributing as was the original intent of the document. We used to have this document setup in such a way that it only included the differences from a central manual¹. This manual used to cover the ins and outs of the Development process. So a dev would read the manual first, obtain the info on how we did business. Then read the contribution guide. The contribution guide would only contain the differences from the manual for the repo in question

Running Doc of helpful stuff

Emoji use in ticket titles

We use emojis in ticket titles for an at glance "what" may still need to be done, task wise. Do note they are not mandatory except for completed ✔️ :heavy_check_mark:

Emoji	Tag	Description
✔️	:heavy_check_mark:	Work on the ticket is complete.
🧪	:test_tube	Tests to be written.
🧹	:broom:	Clean-Up tasks to be completed.
🔍	:mag:	Tasks that require confirmation / Checking.
📘	:blue_book:	Documentation Task
number 1️⃣	:<number word>: :one:	How many tasks need to be completed. numbers zero through nine are available.

With the exception of completed. Only tasks that cease being worked on should have emoji's added. This then enables when looking at the backlog of work, what needs to be done. Additionally, as a task is completed, the emoji must be removed from the title.

Branching

TL;DR

1. Fork the repo.
2. Create your branch from feat-next-release.
3. PR comes back to our feat-next-release branch

Within our repositories we use multiple branches with each serving a different purpose. The following branches are always present:

• master Contains the latest release.

• development Staging branch.

• feat-next-release Working branch for features.

Master Branch

Only maintainers can work on this branch. The only way that commits will occur on master is by merging from development branch. When merging to this branch, our auto-bump CI job bumps the version and creates a git tag which matches the version being released.

Development Branch

Considered the staging branch. Commits only ever remain on this branch for as long as required for CI jobs to complete and pass as necessary. Unless the branch is for a bug fix, commits will come from merging from the feat-next-release branch.

The intent is that this branch remain clean so that if required, an immediate bug fix can be released without having to wait.

[!NOTE]

When a commit (this includes all commits from merging a branch) reaches development and said commit contains a "commit footer close command" The issue will close automagicaly.

feat-next-release

This branch is the default working branch. Unless you are working on a bug. This is where your forks merge request must merge to. Normally this branch will remain un-merged from development branch until whatever is being worked on is in a releasable state.

[!IMPORTANT]

Whenever any commit is made to the development branch, This branch must be rebased on the development branch.

Branches Visualisation

Below is a visual representation of how we do branching, with work occurring from right-to-left. Take note that merges only occur down, never up. With the exception of a rebase, this enables the git tree to remain linear.

                o-----o-----o-----o             o-----o-----o-----o----- feat-next-release
               /                  |            /                  |
        T-----o-------------------o-----T-----o-------------------o----- development
       /                               /
-------o-------------------------------o-----o--------------------------- master

Fig 1. Git commit graph illustrating the project's branching model. Development proceeds from right to left, with feature branches periodically integrated into the development branch and selected changes promoted to master.

Key for Fig 1 is as follows:

• - connecting line

• o A commit

• | Rebase merge

• / Merge commit

• T Git Tag

Ticketing / Issues

Issues are used within our projects to track from a developers perspective, work that needs to be done. We use a variety of issue types, they are:

• Epic

• Feature

• Story

• Task

• Bug

• RFE

• Incident

Whilst anyone can raise an issue, it's important that the right issue type is used. With the exception of a Story (which can be upgraded to an Epic if required), choosing the wrong ticket type will only waste peoples time as you will be required to migrate the issue to one of the correct type.

Epic

An Epic (Epic User Story) is an extension to a Story (or User Story). Their intent is for a non-technical person (normally a project Manger) to plan a module (large set of features) or feature set that has many moving parts. Work to be completed as part of an Epic is always broken down into smaller chunks. As the Epic does not capture the finer features as a whole. The work is planned further in sub-issues, Feature or Story.

Feature

A Feature is basically the same as an Epic, this includes their usage. Normally a Feature is added as a sub-issue to either an Epic or another Feature issue as part of a chain. Like an Epic, work is planned further in sub-issues, Feature or Story.

Story

A User Story or Story for short is the same as an epic in so far that a non-technical person is the one who plans / creates the issue. A Story is for one single feature.

Task

A Task is for developers. They are by nature technical and used for work that only a developer can complete. Epics, Features and Stories, don't capture everything required to implement the feature. So as part of the developers workflow, they will use a Task to plan out the technical side of the work to be completed. Where possible we have Task templates available for different workflows. If you find a workflow, that could or possibly should be templated. Please feel free to, Ironically, raise a Task to have this addressed.

Bug

A Bug is for reporting an issue with the software. Its intend is two-fold. It captures the details of what is wrong with the software and provides the mechanism for us to investigate not only the bug itself but our workflow in the case of improving processes so as to reduce re-occurrence.

RFE

An Request for Enhancement or RFE for short is for requesting that an existing feature be improved in some way. Apart from its name, for all intents and purposes is the same as a Story.

Incident

An incident is for use by either a developer or maintainer. They are for tracking service outages in relation to the project itself, this includes CI. As an example, Github actions become unavailable.

Links

• docs(development): Reorganise the contribution guide #1192 (review)

Tasks

• Ensure that launching a dev environment is simple (VSCodium / VSCode)

  • chore: Hit the ground running development #1200
  • Settings need to be adjusted so they work in dev from clean clone. Tie to debug

• Setup demo environment
  Enables end-users and developers to view product. For the latter also enables visualisation and viewing features.

• Re-create the Developer manual

  • Style Guide
    In the meantime look at code from myself to deduce

    • Scoped blocks ref: test(api): Assert the organization field excludes the global organization #1216 (comment)

  • Repo setup

  • Branching

    • note: Devs should branch from the feat-* with a PR back to it.
      FYI: in this repo, CI tests are conditional on branch. if master, development, feat-* then all tests run (~3hours / ~1hrs otherwise).

  • Templates, inc/usage. (Epics, Features, Stories, Tasks, Bugs and PR)

    • PR Template to be explained and clearly -> fix(access): Give the entity Base serializers unique schema component names #1199 (comment)

  • Language to use
    Australian English (Closely follows British English)

• Commits

  • Conventional Commits used
    • Explain its usage so it's clear -> docs(devops): Name the feature flag serializer schema components uniquely #1226 (review)
  • Commit footer to contain refs. i.e. test(api): Assert the organization field excludes the global organization #1216 (comment)

• Review development docs

  • Update Serializer requirements for drf naming -> fix drf spectacular warnings #361 (comment)

• Review testing docs

  • Add pytest usage of marks, i.e. xfail -> https://github.com/nofusscomputing/centurion_erp/pull/1216/changes#r3701285290

Footnotes

1. Central manual was never migrated when the current iteration of the website was migrated to. ↩

[louzolo123]

Hi @jon-nfc as requested, here are the friction points I hit while setting up a local non-Docker development environment as a new contributor. Environment: Python 3.14, SQLite, running the API plus the UI (centurion_erp_ui) from source. Suggested fixes included where I have one; happy to help implement any of them.

Blocking — the app won't serve / is unusable out of the box

1. Empty SECRET_KEY → every request returns HTTP 500. The base settings set SECRET_KEY = None and only load overrides from /etc/itsm/*.py (SETTINGS_DIR is hard-coded and needs root). There is no documented way to provide a SECRET_KEY for a local, non-Docker, non-root dev server, so the guide's Quick Start (python manage.py runserver 8002) 500s immediately with "The SECRET_KEY setting must not be empty."
   Suggestion: document a local settings file for development, or allow SECRET_KEY to be read from an environment variable.

2. A fresh superuser sees a completely empty navigation menu, which makes the app look broken. CenturionUser.has_perm does not honour Django's is_superuser; permissions come solely from Roles assigned within an organisation, and the nav (OPTIONS /api/v2) only lists entries the user has permission for. Until you manually create a Tenant + a Role with permissions + assign the user, nothing is usable. (Related: Current Permissions model prevents admin panel access #1107, Organization manager cant view organization #425.)
   Suggestion: seed a default organisation/role, provide a management command, or document the required steps.

Feature flags

3. Ticket models (incident/change/problem), ITAM asset base, accounting and git repos are behind feature flags that are only enabled by the if DEBUG or RUNNING_TESTS: block at the bottom of settings.py. This isn't obvious, and without the /etc/itsm mechanism it's hard to turn them on locally — a fresh instance shows an empty nav and the Incidents page errors.
   Suggestion: document this (you kindly pointed me to it), or make it easier to enable in local dev.

UI ↔ API (UI run from source on :3000)

4. localhost vs 127.0.0.1 mismatch causes a 401 login loop. If the UI is opened on localhost:3000 while the API is 127.0.0.1:8002, the session/CSRF cookies (set on 127.0.0.1) aren't sent, every API call 401s and the UI bounces back to login. Everything must stay on 127.0.0.1.
   Suggestion: note this in the dev docs.

5. CORS is not configured for the UI origin by default, so browser calls from the UI to the API are blocked until CORS_ALLOWED_ORIGINS is set.
   Suggestion: a documented dev default for the UI origin.

6. LOGIN_REDIRECT_URL is hard-coded to http://127.0.0.1:3000. That's fine when the UI is on :3000, but the post-login redirect fails (connection refused) if the UI is served elsewhere (e.g. the prebuilt UI image).

Tooling / make / dependencies

7. make prepare doesn't exist (it's listed in .PHONY but there's no rule; it has become make prepare-python). Already flagged in docs(development): Reorganise the contribution guide #1192.

8. make prepare-python / prepare-docs fail on a fresh clone because they cp from git submodules (website-template/, gitlab-ci/) that aren't present (no .gitmodules), which also breaks make lint and make docs.

9. deploy/docker-compose.yaml mounts deploy/settings.tmp.py, which isn't in the repo, so docker compose up fails out of the box. (Noted you've said compose isn't a supported deployment method — flagging for completeness.)

10. Python 3.14: mysqlclient, psycopg2 and uwsgi in requirements_dev.txt fail to build (missing system dev headers), breaking pip install. They aren't needed for a SQLite dev server. This is specific to Python 3.14 — the project targets 3.11 — so more of an FYI than a project issue.

Possibly actual bugs (happy to raise as separate issues if you'd like)

• UI hard-crashes on the Incidents page when the ticket feature flag is disabled (Error: URL undefined does not match... [/api/v2=undefined], from URLSanitize/Ticket), rather than degrading gracefully. (In centurion_erp_ui.)
• ticket_action_comment signal raises AttributeError: '..._before' (core/signal/ticket_action_comment.py:84) when a ticket is saved outside the normal request flow — _before is assumed to always exist.

Docs

• Several inaccuracies in CONTRIBUTING.md are already being addressed in docs(development): Reorganise the contribution guide #1192.

Happy to open separate bug issues for the two items above and to help with fixes for any of these. Thanks!

[jon-nfc]

Hi @jon-nfc as requested, here are the friction points I hit while setting up a local non-Docker development environment as a new contributor. Environment: Python 3.14, SQLite, running the API plus the UI (centurion_erp_ui) from source. Suggested fixes included where I have one; happy to help implement any of them.

3.14?? not yet supported, 3.10 -> 3.13 is was tested, with 3.11 default. happy it works though.

Blocking — the app won't serve / is unusable out of the box
Empty SECRET_KEY → every request returns HTTP 500. The base settings set SECRET_KEY = None and only load overrides from /etc/itsm/*.py (SETTINGS_DIR is hard-coded and needs root). There is no documented way to provide a SECRET_KEY for a local, non-Docker, non-root dev server, so the guide's Quick Start (python manage.py runserver 8002) 500s immediately with "The SECRET_KEY setting must not be empty."
Suggestion: document a local settings file for development, or allow SECRET_KEY to be read from an environment variable.

Agreed. settings does exist in docs, however misses the secret key -> https://nofusscomputing.com/projects/centurion_erp/administration/installation/#settings-file

A fresh superuser sees a completely empty navigation menu, which makes the app look broken. CenturionUser.has_perm does not honour Django's is_superuser; permissions come solely from Roles assigned within an organisation, and the nav (OPTIONS /api/v2) only lists entries the user has permission for. Until you manually create a Tenant + a Role with permissions + assign the user, nothing is usable. (Related: Current Permissions model prevents admin panel access #1107, Organization manager cant view organization #425.)
Suggestion: seed a default organisation/role, provide a management command, or document the required steps.

Feature flags
Ticket models (incident/change/problem), ITAM asset base, accounting and git repos are behind feature flags that are only enabled by the if DEBUG or RUNNING_TESTS: block at the bottom of settings.py. This isn't obvious, and without the /etc/itsm mechanism it's hard to turn them on locally — a fresh instance shows an empty nav and the Incidents page errors.
Suggestion: document this (you kindly pointed me to it), or make it easier to enable in local dev.

The sole purpose of feature flags is so that the end user cant use the feature behind the feature flag. and the reason they are unlocked when if DEBUG or RUNNING_TESTS is so a developer can work on. feature flagging is essentially for developers only. but yes docs for devs are required. Admin docs cover serving them -> https://nofusscomputing.com/projects/centurion_erp/administration/devops/feature_flags/

UI ↔ API (UI run from source on :3000)
localhost vs 127.0.0.1 mismatch causes a 401 login loop. If the UI is opened on localhost:3000 while the API is 127.0.0.1:8002, the session/CSRF cookies (set on 127.0.0.1) aren't sent, every API call 401s and the UI bounces back to login. Everything must stay on 127.0.0.1.
Suggestion: note this in the dev docs.

yes docs. as for localhost vs 127.0.0.1 always default to ip address as this always works regardless. the ip address is whats used within setup too.

CORS is not configured for the UI origin by default, so browser calls from the UI to the API are blocked until CORS_ALLOWED_ORIGINS is set.
Suggestion: a documented dev default for the UI origin.

agreed, although settings requires a full workover. This is not a priority however.

LOGIN_REDIRECT_URL is hard-coded to http://127.0.0.1:3000. That's fine when the UI is on :3000, but the post-login redirect fails (connection refused) if the UI is served elsewhere (e.g. the prebuilt UI image).

see kubernetes manifests in this PR -> nofusscomputing/kubernetes#22 this go par-in-par with the required settings re-write.

Tooling / make / dependencies
make prepare doesn't exist (it's listed in .PHONY but there's no rule; it has become make prepare-python). Already flagged in docs(development): Reorganise the contribution guide #1192.

make prepare-python / prepare-docs fail on a fresh clone because they cp from git submodules (website-template/, gitlab-ci/) that aren't present (no .gitmodules), which also breaks make lint and make docs.

i use prepare-python without issue. what issue did you have? as for prepare-docs and the git submodules didnt you remove that? I was under the impression it was so.

deploy/docker-compose.yaml mounts deploy/settings.tmp.py, which isn't in the repo, so docker compose up fails out of the box. (Noted you've said compose isn't a supported deployment method — flagging for completeness.)

Thanks for flagging. As long as it works for the integration tests make test-integration end user support wont be provided.

Python 3.14: mysqlclient, psycopg2 and uwsgi in requirements_dev.txt fail to build (missing system dev headers), breaking pip install. They aren't needed for a SQLite dev server. This is specific to Python 3.14 — the project targets 3.11 — so more of an FYI than a project issue.

3.13 is the highest supported as the code is tested against it. the intent for centurion is that its always deployed to production via the supplied container and to kubernetes. dev on the other hand, is fine for runserver etc, as they have the expierance to address any issues with pip and the like.

Possibly actual bugs (happy to raise as separate issues if you'd like)

UI hard-crashes on the Incidents page when the ticket feature flag is disabled (Error: URL undefined does not match... [/api/v2=undefined], from URLSanitize/Ticket), rather than degrading gracefully. (In centurion_erp_ui.)

if it's behind a feature-flag its because its not ready. looking at #1181 for current priorities

ticket_action_comment signal raises AttributeError: '..._before' (core/signal/ticket_action_comment.py:84) when a ticket is saved outside the normal request flow — _before is assumed to always exist.

if it's behind a feature-flag its because its not ready. looking at #1181 for current priorities

Docs
Several inaccuracies in CONTRIBUTING.md are already being addressed in docs(development): Reorganise the contribution guide #1192.

I was under the impression that #1192 addressed these? is this not the case.... (ok, just went and looked at. fyi, please don't notate things that are no longer a problem. I requires considerable time to go and look when there is no issue in the first place or it's already addressed. For a project like centurion that covers many thousands of moving parts it's very easy not to know what was happending an hour ago let alone a few days ago.)

Happy to open separate bug issues for the two items above and to help with fixes for any of these. Thanks!

Please always log bugs immediately. That is if they are not behind feature-flags.