Ceci est une ancienne révision du document !
The last few months have seen me spending more time trying to collaborate with other people (on statically generated websites, generally). In doing so, I’ve discovered a system that I find works well for me, and for most of the people I’ve worked with. As such, I wanted to share my method with my readers, and a few gotchas I ran into along the way.
The Setup
I start by setting up any project in a private git repository on GitLab, and sharing the repository with other people (or having the other person set it up, depending on who should have ownership of it). Once the repository is created, I bootstrap out the folder structure and install the tools we need (such as a package.json for Node). The reasoning here is simple - I want a repository where the major structure won’t change too much over the course of the project, and having control over who has access is useful at the start of a project. If you want to open-source it later, just change the access level of the repo.
Once I’ve pushed the basic structure into the repo, it’s usually a joint effort when it comes to creating or carrying over content. I’ll usually set up an example or two as guidelines to follow, but I find having the other person generate as much content as possible allows them to feel comfortable with the process quicker.
Once the content is largely there (even if in draft form), that is when I start creating templates and shortcodes, or tweaking standard settings for special use-cases. The reason for this is pretty simple - if the content isn’t there, it’s hard to tell what repeats often enough to warrant a shortcode, or what elements you want to put into a partial template to reduce repetition.
Managing the actual commits and repository is done using GitHub Desktop or the command-line (although the desktop app is very user friendly for those less comfortable on the CLI).
That’s pretty much it. All the discussions and bug tracking happens in the repository itself. If documentation is required, I’ll use the Wiki function. If you want to have a collaborative brainstorming session, I wouldn’t recommend trying to fit it all into an issue on GitLab, but something like Discord/Wire/Slack/etc. can help a group quickly plan out ideas. Alternatively, you can go old-school with a good ol’ phone call.
Why GitLab?
I started using GitLab before GitHub offered private repositories to free users, which is the main reason I’m still using it. I also just generally find the features offered in GitLab are a little less tucked away for new users to adjust to.
I’ve never had a repo go over the 10GB storage limit, and the issue tracker allows people to assign tasks to themselves and plan time estimates out. Overall, it’s a pretty nice choice for a project planner that everyone can access.
Gotchas
First and foremost, you need to make sure you’re using a good .gitignore before you start working with a lot of static site generators. At the bare minimum, you should make sure to ignore node_modules/ and .DS_Store. I also include the output files for the generated site, any cached folders, the Resources folder in the case of Hugo, and any other hidden files that can show up. The reason for this is really quite simple - it slows down your pushes, and the node_modules files need to be installed on the client anyways, so there’s no benefit to keeping it in the repo.
Also, try to commit groups of files at a time using GitHub Desktop, as it’s easier to roll back a feature if each commit is dedicated to one change or topic. This also doesn’t need to be done after every change, but just take some time to check/uncheck the corresponding files while creating the commit. You can also do this in the CLI, but it requires you adjusting the commit, or adding things manually instead of with “git add .”
Merge conflicts - sometimes you start a change while someone else is plugging away remotely, only to find out you need to pull before you can push your changes to the server… Then it turns out that some of the changes you’ve made were done by someone else too. It can be a bit of a pain, but there’s nothing more to do than to go through and sort out any conflicts that can’t be automatically remedied. Just keep this in mind, and remind the other people you’re working with to pull regularly (in the day and age of Dropbox, some beginners have trouble to remember it’s a manual sync).
Image files - those you’re working with should have a shortlist of things to do to reduce overall image sizes. Since a lot of images from DSLRs or mirrorless cameras (and even some phones) can have massive resolutions, it’s a good idea to reduce them down. If you don’t know what size you want exactly, you can still make assumptions about the maximum size you’ll ever need. Crop or scale images before committing them to the repository. It will make the pushes run smoother, and save space in the long run.
Issues - in GitLab, I tend to put multiple items in a single issue (such as “design issues” full of CSS changes that need to be fixed). As I go through fixing them, I use strikethrough formatting to show which items are done and which are not, while also commenting the commit hash value. This way, anyone who reads the issue can get a good grasp on the timeline of edits, and I can check back to see when exactly I fixed an issue (in case it’s mistakenly re-created later). Also, if you aren’t subscribed, tagged, being replied to, or assigned to an issue, you won’t get email notifications for comments. Keep that in mind if you want to receive them anyways.
Can I use this for other things too?
Sure! You don’t need to be a programmer to use git. I can see this approach being useful for managing documentation for something, or a curated cookbook (as I have done for C&C at one point). Even if the repository stays largely empty, you still have access to an issue tracker, Wiki, and other useful tools.
Conclusion
I hope this article is helpful to anyone who is trying to collaborate with other people, but hasn’t yet found an ideal way to keep everyone up to date. If you have any comments, questions, or suggestions, feel free to email me at lswest34+fcm@gmail.com.