feat: Extend tutorial to include basic explanations of how to use git…#13
feat: Extend tutorial to include basic explanations of how to use git…#13Dutchmen04 wants to merge 21 commits into
Conversation
…hub desktop. Expandguidelines so there are no more todos.
|
Nicely done! The instructions are quite accessible and clear in my opinion. I just noted a few points we might want to |
fqixiang
left a comment
fqixiang
left a comment
There was a problem hiding this comment.
@Dutchmen04 Many thanks for making a great start on this PR! I think the content is very good, but the presentation/delivery can be improved. Some suggestions:
- Use screenshots, concrete examples and/or code snippets to guide researchers.
- Avoid using long sentences without clear structure indicators like commas. They can be difficult to parse for many readers. Likewise, avoid long paragraphs, if possible.
- Use more section titles to improve readability of the documents. Having a clear structure also helps readers to navigate and identify relevant sections quickly.
Co-authored-by: Qixiang Fang <q.fang@uu.nl>
Co-authored-by: Qixiang Fang <q.fang@uu.nl>
Co-authored-by: Qixiang Fang <q.fang@uu.nl>
|
@Dutchmen04 Hi Max, you requested my review but I see that there are still some changes to be implemented from the last review. Could you double check and pin me again once it's ready? An overall comment: the Basic-tutorial.md is currently text heavy. Would be great if you can make it easier to follow for a non-technical person (e.g., with screenshots, bullet points, shorter paragraphs). |
Dutchmen04
force-pushed
the
feat/extended-tutorial
branch
from
1c3534c to
ec48b8a
Compare
|
Looks great, I have added a few comments to mention the mandatory PR review and protected 'main' branch. Other than that I can already approve it. |
Vlad-Andres
left a comment
Vlad-Andres
left a comment
There was a problem hiding this comment.
Approved given you mention somewhere that only repo admins can bypass the '1 approval required rule' for PR merging.
| 2. You create a new branch where you will change said thing. (A branch is just a copy of the project) | ||
| 2. You create a new branch where you will change said thing. | ||
| 3. You make some changes and you commit and push these. Likely this will happen multiple times as this change consists of multiple smaller changes. | ||
| 4. You have changed what you wanted to change so you create a PR. |
There was a problem hiding this comment.
We added a ruleset at the organization level that disallows merging PR if they don't have at least 1 approval so here I suggest step 5:
5. You assign one reviewer to the PR, for example someone from the SoDa Team.
6. When your PR has been approved you can click 'Merge'.
| 1. It often helps to describe clearly what you've done. Start off with "fix:" for example when correcting a typo. If this was in a readme the summary would then read "fix: correct typo in readme". There are different ways to start the summary depending on what type of task you did. An overview can be found in the guidelines. The description is useful when you did something complex as it gives the opportunity to explain why you made certain choices in your new version. | ||
| 2. This depends on the purpose of the branch. If you are adding an extra feature you would want to call it something else compared to when you do a bugfix. The exact naming conventions can be found in the guidelines document. | ||
| 2. This is a question even seasoned developers struggle with. General advice here would be that once you start working on some change (feature/fix/chore anything really), and you are working on that branch, to only have commits that are in direct service to that change. If it is something that you encounter which is not directly linked, but you want to fix it, it is probably best to first finish the existing change and then move on to that task. This helps keep branches focussed. | ||
| 3. If you or a collaborator has made changes on a branch you can start a PR on Github by going to "pull requests" and then clicking on "New pull request". In an ideal scenario no other changes have been made since you started working on a branch and you have people that are also working on the project. These people can then review the changes you've made and give an honest assessment of the quality of the code. In the case that other changes have been made you probably have merge conflicts. In this case you first need to merge main into your branch and resolve conflicts locally after which you can merge still. If there is no one to review your PR you must do this yourself. In this case be honest about the quality of the code and whether there are still improvements that need to be made before it can be merged to main. No newline at end of file |
There was a problem hiding this comment.
If you could also mention here that having at least one approval is mandatory, if they are working alone they can ask SoDa people for that.
3 participants
…hub desktop. Expand guidelines so there are no more todos.