feat(developer guides): create initial guides for hiring developers, … #29

ScuffedNewt · 2025-10-14T20:20:14Z

…getting hired, and working with multiple developers

addresses issue #20

…getting hired, and working with multiple developers

AW0005 · 2025-10-14T21:32:16Z

I feel like it might be good to summarize the two main ways that a developer can contribute to an existing site when hired under the "hiring a dev" section and what an owner needs to do help set that up. The two ways being pushing to a github vs pushing straight to the server.

liwoyadan · 2025-10-14T23:14:53Z

Agreeing with Moif; a short explanation between what the key differences are especially security-wise in terms of a developer having access to a shared repository vs a developer having direct access to one's webserver I think might be really beneficial, and probably emphasizing the importance of it given I've met a couple site owners who very quickly toss over SSH credentials because they think making a repository on Github is too much work but don't understand the security implications of doing that.

I do actually have a copy and paste message I wrote (...5 years ago now...) that has the steps outlined on how a site owner can create a private repository, push their code there, and invite a developer in as a collaborator in about ~6 steps that I can throw in if that's also helpful? Though I'm not sure if that's more useful on these pages or on a more general page since hiring a dev isn't the only situation you'd create a private repo for. (thinking emoji)

ScuffedNewt · 2025-10-15T07:56:17Z

Good idea, I did briefly mention it but yes I do think it's a good investment to make sure people are clear especially hearing your example of people handing over SSH keys willy nilly min

If you'd like to send that paragraph sure, otherwise I'll try cook something up myself!

We could also stick it in a general page, I'll mull it over where best to go

liwoyadan · 2025-10-15T08:18:01Z

My copy and paste (slightly edited to be more general and not have my email) is:

To set up the private repository on Github, you would need to first have an account on https://github.com and:

Once logged in, hit the + button on the upper right corner and select 'New repository'

You can name the repository whatever you'd like (most commonly named either the site's name or similar i.e. lk-speciesname), set it to private, and then hit Create repository (you don't need to fiddle with the other settings there)

You will then be shown a copyable URL in the "Quick setup" box, it should look something like https://github.com/username/repository-name.git; you will want to copy this URL

On the Sourcetree program (or other similar git gui) hit Settings and, just like adding your site's webserver as a remote as detailed in initial setup guides, add the URL you were given as a remote - you can name this remote something like github-repo

Once added you can hit the Push button, select the new remote you added with whatever you've named it, and hit push to push all of your local site files to the repository. After this, you can refresh your repository's page on Github and see that all the files are now there!

Afterwards, hit Settings on the repository's links at the top and then Collaborators under the subtitle Access; there you will be able to select 'Add people' and can either input the email or Github username of the developer you'd like to add to this private repository as a collaborator. They will receive an email invitation to join!

⭐ During step 5 Sourcetree may prompt you for extra authentication to verify your Github account and that you can access the private repository; it usually tells you what is needed (like a personal access token, sometimes you can just input your account's credentials) and this can generally be googled for a tutorial on setting it up. If you decide to go the PAT (personal access token) route, you can find Github's own information on how to do so here; if using a classic PAT you can input it directly into your repository remote's URL on Sourcetree, i.e. if your PAT is ghp_12345678910, you can add it into the URL after the https:// with an additional @ before the remainder of the remote URL like https://ghp_12345678910@github.com/username/repository-name.git which will allow you to access the private repository with the permissions you set on the token on creation.

itinerare · 2025-10-15T09:53:08Z

Oh, yeah, definitely nthing that. Honestly, I think regardless of how we structure the info that we should push it more as the recommended way of handling collaboration? And recommend fairly strongly against just handing over SSH credentials.

itinerare · 2025-10-15T11:45:04Z

docs/guides/getting-hired.md

@@ -0,0 +1,53 @@
+# Getting Hired (for Developers)
+
+Thank you to [itinerare](https://github.com/itinerare) for providing the basis of this guide!


This is thoughtful, but I think fine to omit-- and keeps the docs cleaner. At the end of the day, it's a group effort anyhow!

itinerare · 2025-10-15T12:02:38Z

docs/guides/getting-hired.md

+In fact, the ToS is so important that we recommend not working with anyone who does not have one, or who refuses to agree to yours. In fact, it is so so important, we are going to have an entire section dedicated to it:
+
+### Terms of Service (ToS)
+The purpose of this document is manifold.


I think it might work better to move the last couple sentences from the prior section here and tweak it to be a bit more formal; something like...

Suggested change

The purpose of this document is manifold.

Having and upholding a ToS is so important that we strongly caution against working with anyone who does not have one, or who refuses to agree to yours. As a thorough ToS is so vital, the following section outlines what it should accomplish in this context and provides some recommendations.

itinerare · 2025-10-15T12:05:01Z

docs/guides/getting-hired.md

+However, it’s not practical to be responsible for its maintenance in perpetuity, especially if it breaks as a consequence of others’ actions, updates, etc.
+
+!!! warning
+    Note that this does not necessarily preclude you from taking on additional work to maintain it, including for pay, just absolve you of the obligation to do so.


This should probably be moved from a callout back to plain text... I'm not sure it needs to be in one, but perhaps more importantly, the one after it is really important and shouldn't be "upstaged", if that makes sense.

itinerare · 2025-10-15T12:08:07Z

docs/guides/hiring-devs.md

+2. **Toyhou.se:** This platform has a section for seeking services.
+
+!!! warning
+    Be extremely cautious when hiring developers from third party platforms. Ensure the developer has relevant experience. We personally DO NOT recommend hiring developers without prior Lorekeeper experience, as the learning curve can be steep.


Suggested change

Be extremely cautious when hiring developers from third party platforms. Ensure the developer has relevant experience. We personally DO NOT recommend hiring developers without prior Lorekeeper experience, as the learning curve can be steep.

Be extremely cautious when hiring developers from third party platforms. Ensure the developer has relevant experience. We personally **do not** recommend hiring developers without prior Lorekeeper experience, as the learning curve can be steep.

Formatting nitpick here, but the message is solid.

itinerare · 2025-10-15T12:09:34Z