search

IIIT-Delhi / byld-website

Static Website for IIIT-Delhi's Software Dev Club Byld
https://iiit-delhi.github.io/byld-website/
8 stars 29 forks source link

Create a Contribution Guide #9

Closed virresh closed 6 years ago

virresh commented 6 years ago

And add information about how to do stuff in the repository for someone who doesn't know where to start

peey commented 6 years ago

We want anyone to be able to suggest updates to this data

peey commented 6 years ago

WIP document here - https://hackmd.io/UrF-liCAQuSVN94qXcXsYA?both, I'm writing a few things up

Question: Where should this go once it's done?

virresh commented 6 years ago

I feel a standard CONTRIBUTING.md would be essential in order to direct users to the appropriate wiki page It'd align our repository towards one that looks much like many other OSS organisations

GitHub wikis are streamlined for only documentation and thus would relieve us of giving push access to source to members in order for them to be able to edit the wiki Although it won't be tied to the site version as it is, but will still be more flexible than something on the main repo

PS: We can edit a wiki exactly the same way we edit any github repository (and the revisions are also stored), the clone link for wiki is provided in the wiki sidebar itself, and editors won't be an issue, we can use anything we like.

For this repo, it's https://github.com/virresh/byldWebsite.wiki.git

virresh commented 6 years ago

Also I just noticed, we aren't limited to Markdown for wikis, we can use a lot of supported stuff, asciidoc, textile, ReStructured Text, etc etc

peey commented 6 years ago

Wiki seems easier. I've made a page here: https://github.com/IIIT-Delhi/byldWebsite/wiki/Contributing

@virresh please add details about what procedure they should follow for pushing changes (assume familiarity with github / include external link for that, just include our practices - at least one review, look at preview, etc)

Also go through what I've written and share thoughts

virresh commented 6 years ago

The Contribution guide looks nice :+1: I've added the standard instructions for pushing changes and some warnings, Language revisions and formatting changes are highly welcome (although I specifically chose the headings so that we can permalink to them, but any other way that will allow us to permalink to the instructions willl also work, I'm not very sure how to do that tho)

peey commented 6 years ago

All pull requests need to come from a separate branch. Under no circumstance shall a PR made from master branch of your fork to master branch of this repository will be merged.

Why is this necessary?

The pull request will be subject to the scrutiny of a continuous integration - Travis, which will build the project. Also once a pull request is made, you will see a deploy preview of your changes via netlify, link will be in the PR's status section (at the bottom in the conversation tab), to help you visualise the changed you've made.

I'm going to reword this because if someone is not familiar with CI, travis or netlify, better to give a short overview here on how it relates to the person making the PR than to provide just links

virresh commented 6 years ago

Why is this necessary?

This is to avoid the very common pitfall that people often overlook when rebasing Rebasing avoids unnecessary commits, but at times when direct fast forward is not available, it ends up changing the commit hash in order to bring it at the HEAD

(Consider a PR that was made from the master branch, before it got accepted, the main repo's master branch got another new commit that doesn't conflict with the PR, now we can do a rebase and merge, but this will rewrite the commit and change it's hash, putting in a different version into the main repository's master than the one inside the PR's master branch. The person would ideally remove their branches once done with it, but won't/cannot remove master, and thus have a different version of the commit

For visualisation, lets say the PR has a commit history A->X, Repo master has a commit history A->Y, a rebase done via github UI will take commit X, and put it at the top of Y after changing it in the process, so now the master looks as A->Y->Z , assuming rebase transformed X into Z, whereas the repository from which the PR was made has a commit history A->X, which is very different from the new master). Unless they are proficient in git, they won't realise what has happened and will end up messing their fork, and maybe even delete it, which will cause other PRs made from that fork to go haywire and we might have no option but to close them, which is a real bad situation.

I'm going to reword this

Sure, I also thought that maybe this won't be descriptive enough.

virresh commented 6 years ago

hit ctrl+f to find it

Just a suggestion, since we are already using git, we might as well promote the usage of git grep It would do a grep search everywhere it can to report stuff that might be relevant

peey commented 6 years ago

I haven't used it. Seems like it searches through all files in the project. Does it also search through commit history though? We may not want that

Also check the page now, I've updated it. The screenshot could be better. TODO: update it next time a PR comes along

virresh commented 6 years ago

Seems good to me :+1: And no, git grep doesn't search through commit history by default, though I think there are some options to do that, but we anyways don't need that

peey commented 6 years ago

For visualisation, lets say the PR has a commit history A->X, Repo master has a commit history A->Y, a rebase done via github UI will take commit X, and put it at the top of Y after changing it in the process, so now the master looks as A->Y->Z , assuming rebase transformed X into Z, whereas the repository from which the PR was made has a commit history A->X, which is very different from the new master).

Educational! I did not know that. I want to include a link to an explanation of this but I couldn't find it on stackexchange. Do you know of any sources? Otherwise I'll link to your comment

Included git grep

virresh commented 6 years ago

http://www.codetunnel.io/merge-vs-rebase-part-3-what-is-a-rebase/ This is the closest I could get that actually explains the pitfalls of rebasing with an example analogy Although no article that illustrates the above point concisely