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.
Les derniers mois m'ont vu passer plus de temps à essayer de collaborer avec d'autres personnes (sur des sites générés statiquement, en général). En faisant cela, j'ai découvert un système qui, je trouve, marche bien pour moi et pour la plupart des gens avec lesquels j'ai travaillé. Aussi, je voulais partager avec mes lecteurs ma méthode et les quelques écueils que j'ai rencontrés pendant ce parcours.
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.
Le paramétrage
Je commence en paramétrant un nouveau projet dans un dépôt git privé sur GitLab et en partageant le dépôt avec d'autres personnes (ou d'autres l'ont paramétré, suivant qui en est propriétaire). Une fois que le dépôt est créé, j'initie la structure des répertoires et installe les outils dont j'ai besoin (tels que package.json pour Node). Ici, le raisonnement est simple : je veux un dépôt où la structure principale ne changera pas beaucoup tout au long du projet ; de plus, avoir le contrôle sur qui y a accès est utile au début d'un projet. Si vous voulez le rendre Open Source plus tard, changez simplement le niveau d'accès au dépôt.
Une fois que vous avez mis la structure de base dans le dépôt, c'est en général un travail conjoint quand il s'agit de créer ou déplacer le contenu. Généralement, je paramètre un ou deux exemples comme lignes de conduite à suivre, mais je trouve que permettre aux autres personnes de générer autant de contenu que possible leur permet de se sentir à l'aise plus rapidement avec le processus.
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.
Quand le contenu est là en grande partie (même s'il est sous forme d'ébauche), je commence à créer des modèles et des codes de raccourcis, et j'ajuste les réglages normaux pour des cas spéciaux d'utilisation. La raison en est assez simple : si le contenu n'est pas présent, il est difficile de dire ce qui se répète assez souvent pour mériter un code de raccourci, ou quels sont les éléments que vous voulez incorporer dans un modèle partiel pour réduire les répétitions.
La gestion des vraies validations et du dépôt se fait en utilisant GitHub Desktop (bureau GitHub) ou la ligne de commande (CLI - bien que l'appli de bureau soit très conviviale pour ceux qui sont moins à l'aise avec la CLI).
C'est à peu près tout. Tous les échanges et la chasse aux bugs se passent dans le dépôt lui-même, Si une documentation est exigée, j'utiliserai la fonctionnalité du Wiki. Si vous voulez disposer d'une session de brainstorming, je ne vous recommanderais pas de la mettre en place dans un article sur GitLab ; mais quelque chose comme Discord/Wire/Slack/etc. peut aider un groupe à mettre rapidement ses idées à plat. Autrement, vous pouvez vous la jouer « vieille école » en passant un bon vieux coup de fil.
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.
Pourquoi GitLab ?
J'ai commencé à utiliser GitLab avant que GitHub n'offre des dépôts privés gratuitement à des utilisateurs, ce qui est la raison principale pour laquelle je l'utilise toujours. En général, j'ai simplement trouvé que les fonctionnalités offertes dans GitLab sont un peu moins camouflées aux nouveaux utilisateurs qui peuvent s'en accommoder plus facilement.
Aucun de mes dépôts n'a jamais dépassé la limite de stockage des 10 Go et le pisteur de problèmes permet aux gens de s'attribuer des tâches à eux-mêmes et de prévoir les temps estimés. Par-dessus tout, c'est un choix plutôt bon pour un planificateur de projet auquel chacun puisse avoir accès.
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 .”
Les écueils
D'abord et surtout, vous avez besoin de vous assurer que vous utilisez le bon .gitignore avant de commencer à travailler avec beaucoup de générateurs de sites statiques. Au strict minimum, vous devriez vous assurer que vous ignorez node_modules/ et .DS_Store. J'ai aussi inclus les fichiers de sortie du site généré, tous les dossiers de cache, le dossier Ressources dans le cas de Hugo et tous les autres fichiers cachés qui peuvent apparaître. La raison en est simple : cela ralentit vos « push », et les fichiers node_modules doivent être installés de toute façon sur le client ; aussi, il n'y a aucun intérêt à les garder dans le dépôt.
Essayez aussi de valider (« commit ») d'un coup un groupe de fichiers en utilisant GitHub Desktop, car c'est plus facile de faire faire marche arrière à une fonctionnalité si chaque commit est dédié à une modification ou un sujet. Ceci n'a pas besoin d'être fait après chaque changement, mais prenez le temps de valider/dévalider les fichiers correspondants quand vous créez un commit. Vous pouvez aussi le faire en ligne de commande, mais cela nécessite que vous adaptiez le commit, ou que vous ajoutiez des choses à la main à la place du « 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.
Conflits de fusion - parfois, vous commencez une modification alors qu'une autre personne travaille à distance, pour découvrir que vous ne pouvez que tirer (« pull ») avant de pousser (« push ») vos modifications dans le serveur… Ensuite, il apparaît que certaines de vos modifications ont aussi été faites par quelqu'un d'autre. Ça peut s'avérer pénible, mais il n'y a rien d'autre à faire que de remonter ses manches pour résoudre chaque conflit qui n'a pas pu être résolu automatiquement. Gardez juste ceci à l'esprit et rappelez aux autres personnes que vous travaillez régulièrement vos « pull » (à l'ère de Dropbox, certains débutants ont du mal à se souvenir que c'est une synchronisation manuelle).
Fichiers images - ceux avec qui vous travaillez doivent avoir un mémo des choses à faire pour réduire la taille globale des images. Puisque beaucoup d'images tirées des appareils photo numériques, reflex ou non, (et même certains smartphones) peuvent avoir des résolutions énormes, c'est une bonne idée de les réduire. Si vous ne savez pas exactement la taille que vous voulez, vous pouvez cependant faire des suppositions sur la taille maximale dont vous aurez besoin. Rognez ou changez l'échelle des images avant de les valider dans le dépôt. Les « push » seront plus faciles et vous économiserez de l'espace sur le long terme.
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.
Problèmes - dans GitLab, j'ai tendance à mettre plusieurs éléments dans un seul problème (comme « problèmes de conception », plein de modifications du CSS qui ont besoin d'être résolues). Quand je les parcours pour trouver une solution, j'utilise un format avec caractères barrés pour distinguer ceux qui sont faits de ceux qui ne le sont pas, tout en commentant le commit avec un « # ». De cette façon, toute personne qui lit le problème peut trouver de bonnes infos sur l'avancement des modifications, et je peux vérifier précisément quand j'ai résolu un problème (au cas où il aurait été recréé par la suite). Aussi, si vous n'avez pas souscrit à un problème, mis une étiquette, mis en réponse ou assigner à ce problème, vous ne recevrez pas de mail des modifications pour vos commentaires. Gardez-le à l'esprit si vous voulez les recevoir de toute façon.
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.
Puis-je utiliser ceci pour d'autres choses ?
Bien sûr ! Vous n'avez pas besoin d'être programmeur pour utiliser git. Je peux imaginer cette approche comme utile pour gérer de la documentation sur quelque chose, conserver un ensemble de recettes (comme je l'avais fait pour C&C à un moment). Même si le dépôt reste largement vide, vous avez toujours accès au pisteur de problèmes, au Wiki et à d'autres outils utiles.
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.
Conclusion
J'espère que cet article aura été utile à ceux qui essaient de collaborer avec d'autres personnes, mais qui n'ont pas encore trouvé une façon idéale de tenir tout le monde à jour. Si vous avez des commentaires, questions ou suggestions, n'hésitez pas à envoyer à un mail à lswest34+fcm@gmail.com.