Thank you for participating in the constant conversation that makes the Beta maṣāḥəft digital research environment possible!
Whether you are interacting with others by creating and reacting to issues, by making and reviewing Pull Requests or in other ways, please take a few instants to read the following remarks to make all interactions as agreeable and efficient as possible.
In all your online communications, please be as clear and concise as possible, while giving all information you feel is relevant.
Please adhere to common rules of orthography and punctuation, which make the reading experience more agreeable.
In order to prevent common misunderstandings, please refrain from the use of irony and rhetorical questions.
One of the strengths of this digital research environment is the diversity of those working with it. Contributors come from various backgrounds and are not all familiar with the same topics. Please remember this, when terminology obvious to you - be it informatical, codicological or philological - is not understood by all.
Remember that the persons interacting here are all, as you, real people and wish to be treated as such. While conciseness is important for all, so is a basic standard of common politeness.
When in doubt about which kinds of behaviour (in editing, answering, commenting, reviewing...) are appropriate, just ask!
- Everyone (= every member of the organization) can comment and read comments
- Everyone can propose changes
- Everyone can use the data
- Everyone can make a branch
- Everyone can commit changes to their branch
- Only the team members can commit to master but are discouraged to do so
- Only the tech lead can commit to master
- Everyone can create a Pull Request
- Everyone can be asked to review a Pull Request
- Team Members have to review a Pull Request if asked
- Other Members can decline to review or ignore the request to review
- Only team members can merge a Pull Request which has been reviewed
- Team members can merge a Pull Request even if it has not been reviewed, but this is bad practice and is discouraged
- No one, ever should use the Force Push option unless adviced to do so by the teach lead of the project
- Everyone can open issues, comment and contribute to the conversaions
Always make sure you are familiar with the Code of conduct. Please use one of the templates. Try to be as clear as possible and detail the problem you are seeing in a way facilitating the work of those who can help to solve it.
For any task you are carring out, big or small, create a new branch from the latest master status. Fetch the origin, pull all updates, and then make your new branch. Any GitHub tutorial, and they abound, is fine here. If you are working on different computers, make sure you PUSH your commits to your branch, if you want to be able to fetch them and progress from another working station. You can make as many commits as you want, but when you make a Pull Request, you are submitting a piece of work of your choice for review, and it is not nice to change it while it is under review.
Make sure you describe your changes enough for a reviewer to be able to know where to focus for their review. Assign a reviewer which knows the stuff you are doing and can provide enhancement. If you do not know who to assign, leave it, the team members will assign it. Try not to make other commits to the Pull Request unless asked in the review.
The number of sensible changes and files changed per Pull Request can be varied, but should be within reasonable limits, considering the work of the reviewers. Usually, one Pull Request for one file with one new line is not reasonable, and neither is one Pull Request for 2000 files with a comma changed in each. Please try to put yourself in the place of your reviewer, make the contents of your Pull Request consistent and describe them in a way that allows others to review your contribution in a reasonable way. In cases of doubt, do ask your reviewers which kinds of Pull Requests they prefer. Please consider that thouroughly reviewing Pull Requests requires a considerable investment of time and concentration from the reviewers, who cannot always interrupt their other commitments to make each Pull Request a priority.
Seeing the file quickly online is no good excuse for bad Pull Requests habits.
It is good practice to start by switching to the PRed branch in your system and start by making sure that the changed files are valid. You can then review only the changes in the system, or look again at the entire files. Focus on
- completeness of encoding
- relevance to the proposed task (if the pr said it marked up names, names should be marked up)
- correctness against the guidelines (which does not mean everything should be done that is documented there)
In general, keep it nice and simple, unless there are errors, our data is open and we welcome diverse contributions. It is not worth trying to have other people encode the same way you do or add the same information you do, but encouraging more precise is always a good thing.
You can then decide: either make the changes directly, which is to be recommended especially for one of and small things, or ask for changes from someone else, which needs not to be the author of the PR in all cases.
Once a review round is finished, leave a comment to say you are done with your review.
It is enough to have 1 accept review to merge, however, if two reviewers have been assigned, there is a chance you are merging before they have finished. Better to drop a comment and ask if it is ok to merge. Ideally the person merging should be different from the one reviewing, although this is often not practical.
If there are conflicts, resolve them before merging, do not ignore them. GitHub does not let you fortunately, but just in case you have another plan... When the review is done, please use Squash and Merge, not only merge, and edit if necessary the comment. Delete the branch after a successfull merge. This should encourage that a new branch or a republication of this branch will happen after fetching the changes to master. reminding the authors of the PR to update their master branch before doing a new branch, is always a nice idea.
Please, always refer to the Guidelines https://betamasaheft.eu/Guidelines/ and add links to them. If your commit is related to an Issue or Pull Request, please add a link in the Comments to the Commit.
All data in the Beta Masaheft Organization is collaboratively edited. We expect that you do your best and that if you see place for improvement, you try to fix it yourself first, if possible. All you do will be aknowledged in all the ways we can. If you do not feel good enough in the encoding to try yourself, you can ask and get support. If you just do not want to try yourself, express your suggestions a clear way, so that others can take their time to fulfill your wishes as an act of kindness.