Improve readme

[eliykat]

🎟️ Tracking

N/A

📔 Objective

I set up the Splunk app for local development today and hit a few pain points, possibly because I'm not familiar with the Python ecosystem. In particular:

• forcing Docker to use the linux/amd64 version of the Splunk image (on a Mac Silicon)
• finding the right Python version and telling Poetry to use it
• installing libmagic, which is not installed by default on Mac

I've added these to the instructions, and also restructured them to be more step-by-step.

Two follow-up questions:

1. are there any objections to me moving these instructions to https://contributing.bitwarden.com where the rest of our documentation lives?
2. pyproject.toml specifies the python version as python = ">=3.7.17", however these instructions refer to Python 3.8 specifically. I received syntax errors when trying to use 3.12, which is what I already had installed on my system. I suggest we probably need to specify ^3.8 - what do you think @WaciX ?

⏰ Reminders before review

• Contributor guidelines followed
• All formatters and local linters executed and passed
• Written new unit and / or integration tests where applicable
• Protected functional changes with optionality (feature flags)
• Used internationalization (i18n) for all UI strings
• CI builds passed
• Communicated to DevOps any deployment requirements
• Updated any necessary documentation (Confluence, contributing docs) or informed the documentation team

🦮 Reviewer guidelines

• 👍 (:+1:) or similar for great changes
• 📝 (:memo:) or ℹ️ (:information_source:) for notes or general info
• ❓ (:question:) for questions
• 🤔 (:thinking:) or 💭 (:thought_balloon:) for more open inquiry that's not quite a confirmed issue and could potentially benefit from discussion
• 🎨 (:art:) for suggestions / improvements
• ❌ (:x:) or ⚠️ (:warning:) for more significant problems or concerns needing attention
• 🌱 (:seedling:) or ♻️ (:recycle:) for future improvements or indications of technical debt
• ⛏ (:pick:) for minor or nitpick changes

[github-actions[bot]]

Checkmarx One – Scan Summary & Details – 2b06cd54-ccbc-4387-91a3-932036b34ac1

No New Or Fixed Issues Found

[eliykat]

Thanks @mzieniukbw , I've continued these changes here: https://github.com/bitwarden/contributing-docs/pull/386

Once that's merged, we can just update this doc to link there.

Re: the Python version - can we specify that it should be =< 3.9? I was more concerned about limiting the use of newer, incompatible versions (3.12 threw errors) rather than bumping the min version (although I see that is what I wrote).

[mzieniukbw]

@eliykat i have just tested other python versions and added a suggestion in https://github.com/bitwarden/contributing-docs/pull/386/files 3.10 works fine, but 3.11 and 3.12 throws errors during package validation (splunk tooling python incompatibility). I don't want to limit the users to specific python versions, so giving them a range, like 3.7-3.10 is fine. We could limit it in the poetry pyproject.toml file, i don't mind.

[eliykat]

I like specifying it in pyproject.toml, it's an easy thing to miss and it's better to get an explicit error than some random runtime failure. I've done that and regenerated the lockfile as required. Now when I try with 3.12:

Current Python version (3.12.4) is not allowed by the project (>=3.7.17, <=3.10). Please change python executable via the "env use" command.

I've also updated the README to point to the contributing docs.