ENIGMA Forums

General fluff => General ENIGMA => Topic started by: forthevin on June 04, 2013, 11:34:10 AM

Title: Proposal for guidelines on changes to the master branch of enigma-dev/enigma-dev
Post by: forthevin on June 04, 2013, 11:34:10 AM
Due to various issues in regards to changes to the master branch of enigma-dev/enigma-dev, I believe it would be useful to have some guidelines on how changes to the master branch should be handled.

The following guidelines are not complete, but should be a good starting point. If the guidelines at some point are accepted, I will post them on the wiki.

Guidelines for changes to the master branch.

The idea behind these guidelines is to help developers and contributors, old as new, making good decisions in regards to the master branch of the repository. It is based off common thought and experience between the developers, and is not meant to be fast and hard rules, but informing and guiding developers. It should be noted that "developers" and "contributors" are used interchangeably in these guidelines.

Change notes:

2013-06-06: Added information on how to use git and GitHub to handle changes.
2013-06-04: Creation of this document.

Purpose of these guidelines:


The purpose of the master branch of enigma-dev/enigma-dev:

The master branch is the generally used branch by both developers and users. Having a common branch enables quick fixing and development, and means users will not have to wait long before getting the newest additions or fixes. Given that ENIGMA is still not fully mature or feature complete, it makes sense to have a semi-stable main branch, which will rarely break games relying on core and established functionality, while still allowing quick development and experimentation on unstable and non-core parts. However, if the master branch breaks core or established functionality all the time, the master branch becomes very unstable for users, and developers will waste time on finding and fixing issues that used to be non-issues. For this reason, it is important to keep the master branch at least semi-stable, rarely breaking core or established functionality.

Possible issues with changes:


Dealing with changes:

When you are in doubt about a change, and whether it should be committed to the master branch, there are several options for dealing with that:


When determining whether a change should be committed to the main branch, it is useful to determine what issues it has. However, it can be difficult to determine all the issues of a given change. To handle this, there are some general guidelines for estimating the potential severity of possible issues of a change.


Using git to handle changes:

git offers several features which can be used to handle changes. One of these features are branches. See http://gitref.org/branching/ for information about what a branch is. In regards to changes, the master branch is the main branch used by users and developers alike. By creating and using a separate branch from the master branch, you can do any changes you want without it bothering anyone else, and let others look at it, possibly fix any issues, and then merge it into master.

For examples on how to use branches, see post 1 (http://enigma-dev.org/forums/index.php?PHPSESSID=nr9v3ca8utr5gvjcbmd37kvoe3&topic=1287.msg13109#msg13109) and post 2 (http://enigma-dev.org/forums/index.php?PHPSESSID=nr9v3ca8utr5gvjcbmd37kvoe3&topic=1287.msg13110#msg13110).

Using GitHub to handle changes:

Another feature is the fork of GitHub, which you can find more information about here: https://help.github.com/articles/fork-a-repo. Basically, a fork creates a whole new repository based on the new one, where you can do any changes you want, and once you would like others to look at it or get it merged into the main repository, you can make a pull request where you describe the changes and other relevant details. If more work is needed, you can make more commits, and it will be reflected in the pull request.
Title: Re: Proposal for guidelines on changes to the master branch of enigma-dev/enigma-dev
Post by: polygone on June 04, 2013, 11:44:23 AM
I will add that I think it's a good idea for any developer to try and look and take note of all the commits that are made. This will reduce the need for fork testing as mistakes can be picked up in this way almost as efficiently and quickly. I do this a lot and find that knowing what commits were made and when comes in handy all the time in dealing with random things that crop up. So am I the only one that currently really does this?

And this whole blame game thing that people like to do with regards to the repo isn't healthy for progress at all. I consider the benefit of progress to massively outweigh the negatives of the odd mistake or regression that might occur. It's hardly like many people are yet using ENIGMA to develop games properly, the progress of the engine is by far the most important thing still at this point. In the future, if more people are developing with it then we will probably want to set-up a more stable repo base by using a common update branch which is properly tested before merging into main. But we're not near that point in the development yet in my opinion, it's more costly to halt the progress with branching and over testing by other developers.
Title: Re: Proposal for guidelines on changes to the master branch of enigma-dev/enigma-dev
Post by: forthevin on June 04, 2013, 12:21:57 PM
I generally look at the commit messages, while I usually skim through the commits themselves. Properly looking through a big commit can take quite some time.

It is true that not many users are affected by regressions yet. However, I believe regressions can hinder development considerably as well, given that it takes time to replicate the bug, isolate and find it, figure it out, fix it, and test that the fix works. That said, I agree with you that we shouldn't be too careful with everything either, since that does take time as well

I personally think that automated regression testing will help these issues a lot. It will decrease the burden of testing considerably, and by making things more stable that way, will also lessen the amount of time spent on debugging. I personally plan to look into it in the future, after I have looked at some other issues such as the synchronization issue.
Title: Re: Proposal for guidelines on changes to the master branch of enigma-dev/enigma-dev
Post by: polygone on June 04, 2013, 12:38:10 PM
I personally think that automated regression testing will help these issues a lot.
We could all use a standard test file when going to test if ENIGMA still compiles after changes so it could serve multi-purpose to concurrently report if any regression has occurred.
Title: Re: Proposal for guidelines on changes to the master branch of enigma-dev/enigma-dev
Post by: Goombert on June 04, 2013, 12:50:03 PM
Oh yes, I complete forgot to post about this, forthevin somebody gave me a great idea in the IRC. They told us to compile a series of "unit tests" so basically we make a mini demo that demonstrates that everything works, paths, graphics, physics, collision systems, kind of a lot like you see with the little demos I program. Make a broad series of them covering everything and use them for ensuring there are no regressions during mergals.

Now polygonz, your argument is good, but it just does not work for what you did with just breaking the mouse code. That is not progress, you could have just left it be the slow implementation on other platforms and then filed an issue on the tracker for one of the platforms maintainers to address. Just removing obsolete code is not progress, can you just imagine if Ubuntu or Linux distros or other open source software did this? My god, it's a disasterous idea, and you seriously need to stop thinking that way. Your mindset and the way you approach this is everything wrong with open source, and why every freaking Ubuntu update has to break something.
Title: Re: Proposal for guidelines on changes to the master branch of enigma-dev/enigma-dev
Post by: polygone on June 04, 2013, 01:01:51 PM
1) I couldn't just leave it slow on other platforms, I was moving things around from universe to try and get the speed increase. It would have been more effort than it's worth for me to change everything around to make the functionality of the mouse position work.
2) It took literally 2 seconds to add that functionality back into the other systems
3) mouse_x/y is useless
4) I would have normally made an issue report and have done on other occasion with something like this, I just forgot on this instance. I made a note in the commit message at least and mentioned it on the IRC.
5) The big difference being here that lot's of people actually use Ubuntu. Whereas we're still trying to get the engine to a point where a proper user-base want to use it. Like I said only at that point should we properly care about things such as this
6) I'm not talking about this crap again :p
Title: Re: Proposal for guidelines on changes to the master branch of enigma-dev/enigma-dev
Post by: Goombert on June 04, 2013, 01:39:21 PM
#1 and #2 are conradictions
#3 is completely obsurd, I'd say about %40 of games or even a lot more, I am lowballing it, require a mouse especially on flash games
#4 you should have probably directed it at josh and not me, because I generally do not care as long as nothing breaks, therefore I ignore about %90 of everything you guys say
#5 no, don't call it progress, you fuck up progress by forcing us to drop anything were doing and fix whatever it is you wan't us to fix
#6 then don't break shit, it is not that fucking hard
Title: Re: Proposal for guidelines on changes to the master branch of enigma-dev/enigma-dev
Post by: polygone on June 05, 2013, 04:09:48 PM
#6 then don't break shit, it is not that fucking hard
Do you know what the optimum strategy is for me to take in order to ensure not break anything? It's for me to not commit anything else. And that's precisely the angle that you guys like to push for when you complain about a largely irrelevant and minor regression like this.
Title: Re: Proposal for guidelines on changes to the master branch of enigma-dev/enigma-dev
Post by: polygone on June 05, 2013, 04:39:52 PM
When I said useless I meant trivial, and it's not going to break compiling. I expected the mouse update to be added back into the linux platform straight away.
Title: Re: Proposal for guidelines on changes to the master branch of enigma-dev/enigma-dev
Post by: polygone on June 05, 2013, 04:49:27 PM
What does it matter that people temporarily couldn't use mouse_x/y for 5 minutes?
Title: Re: Proposal for guidelines on changes to the master branch of enigma-dev/enigma-dev
Post by: Goombert on June 05, 2013, 04:50:46 PM
Lol, it was a week polygonz, in fact I haven't pulled yet and it is still screwed up on my system.
Title: Re: Proposal for guidelines on changes to the master branch of enigma-dev/enigma-dev
Post by: polygone on June 05, 2013, 04:51:44 PM
It wasn't a week that people were using it, it would have been reported. And as soon as it was reported anybody could have resolved it within 5 seconds. In any case nobody was releasing a game in that period of time, it was irrelevant.
Title: Re: Proposal for guidelines on changes to the master branch of enigma-dev/enigma-dev
Post by: Goombert on June 05, 2013, 05:12:19 PM
Polygonz you are way too thick headed, if you see nothing wrong with your statement about people releasing games, then I am afraid there is nothing more to discuss. I do not understand what part of people need the mouse functionality locally in order to make a game or even test/program/develop and all of our source code check out systems including the Windows installer go for the latest revision. And it was a week I first had it when you were doing the stuff to speed up the fps rate and did not say anything until a week later when whats his face reported it to me, and I did not say anything to you because I assumed you were just commenting shit out temp. I did not know you were purposely breaking it indefinitely.
Title: Re: Proposal for guidelines on changes to the master branch of enigma-dev/enigma-dev
Post by: polygone on June 05, 2013, 05:29:13 PM
If somebody tried it, it would be clear to them straight away that the mouse positions were not being updated, then they simply say so and it's fixed straight away. And this is exactly what happened, if it took a week for it to get mentioned then it suggests that they're not in as much use as you probably though. No harm was done by this at all, nobody's progress was delayed. And now thanks to my changes ENIGMA runs faster and with a commit back that took 2 seconds to do the mouse update is back to normal.

You're the one that's thicker header.
Title: Re: Proposal for guidelines on changes to the master branch of enigma-dev/enigma-dev
Post by: Goombert on June 05, 2013, 05:38:48 PM
Of course polygonz, you are right all of our bugs are fixed STRAIGHT AWAY amirite? Thats why we have sooo fuckin many unaddressed tickets on the tracker, isn't it? And no I am not thick headed I listen when Josh and Ism explain this stuff about how to properly be commiting and ensuring there are no regressions etc.
Title: Re: Proposal for guidelines on changes to the master branch of enigma-dev/enigma-dev
Post by: forthevin on June 05, 2013, 05:43:37 PM
Gahhhh. Thinks are getting too heated over mouse_x/mouse_y. polygone, it would be nice if you are a little bit more careful with your commits in the future. Others, mouse_x/mouse_y was likely a mistake from polygone's side, but hardly the end of the world.

I would also appreciate any comments on the guidelines I proposed.

polygone: I am currently looking into set_synchronization, and noticed that it had been commented out earlier in the Windows platform system. Do you remember why we did that? The code looks like it could work, though I haven't tried it out yet. I also wonder if it is related to dependencies, including glew, which may have been solved by the new bridges that have been made.

Robert: I think unit testing would be a very nice thing to have. I have thought about it myself, and I think it would also be nice to have different groups of tests so to say, such that if you made changes to graphics, you can run just tests related to graphics without running tests related to other stuff like sound. That said, I haven't looked much into it yet. I also think it would be very nice if the tests we make at some point can be easily be integrated into the automated regression testing on the site that I and Josh briefly talked about in the thread about the site.
Title: Re: Proposal for guidelines on changes to the master branch of enigma-dev/enigma-dev
Post by: polygone on June 05, 2013, 05:46:21 PM
Of course polygonz, you are rigth all of our bugs are fixed STRAIGHT AWAY amirite?
I wasn't referring to all the bugs, I was referring to this regression which the cause was perfectly known already.

polygone: I am currently looking into set_synchronization, and noticed that it had been commented out earlier in the Windows platform system. Do you remember why we did that? The code looks like it could work, though I haven't tried it out yet. I also wonder if it is related to dependencies, including glew, which may have been solved by the new bridges that have been made.
Yes, it was because of the dependencies.
Title: Re: Proposal for guidelines on changes to the master branch of enigma-dev/enigma-dev
Post by: Goombert on June 05, 2013, 06:01:17 PM
Ya polygonz and we got enough bugs already without you implementing ones for the fuck of it.


@forthevin, no I was not aware I must not have payed attention to the website post, didnt really interest I am fine with the site except these forum bugs like the PM stuff.
Title: Re: Proposal for guidelines on changes to the master branch of enigma-dev/enigma-dev
Post by: polygone on June 05, 2013, 06:05:23 PM
Ya polygonz and we got enough bugs already without you implementing ones for the fuck of it.
It's not there any more.
Title: Re: Proposal for guidelines on changes to the master branch of enigma-dev/enigma-dev
Post by: Josh @ Dreamland on June 05, 2013, 06:06:06 PM
polyfuck: How important a particular feature is does not pertain to the issue at hand. The issue is that the tracker is overflowing with little shit, the IRC is full of people who can't get the installer working, and amid all of that chaos, someone mentions, "Oh hey, mouse_x and _y aren't working."

Anyway, thanks much for the post, forthevin.
What I'm personally thinking is that we should do what we did on the SVN, only a little cleaner. I propose that everything in master be deemed "stable"; that is, no changes are made to it which have not been tested. Changes for testing are merged into the "testing" branch, from the "development" branch, when it's deemed that it might be a good time to push to stable.

Bug reports should be fixed in the most stable branch exhibiting the bug. That is, a bug should be fixed in master if it exists in master, otherwise it should be fixed in testing, or otherwise in development. If a bug is fixed in master, the fix is then merged into testing and development. If a bug is fixed in testing, it is merged into development. Bugs fixed in development, as stated, should have only been fixed there because they are absent from master and testing.

What I've just described is so simple, it's probably standard. The only reason we *aren't* doing that is because we failed miserably at it with the SVN, because no one ever remembered, "Hey, this would be a good revision to mark for (testing|stable)!"

If I thought we were responsible enough not to have a three-month-dead master branch on that system, I'd be interested in pursuing it.
Title: Re: Proposal for guidelines on changes to the master branch of enigma-dev/enigma-dev
Post by: polygone on June 05, 2013, 06:08:28 PM
polyfuck: How important a particular feature is does not pertain to the issue at hand. The issue is that the tracker is overflowing with little shit, the IRC is full of people who can't get the installer working, and amid all of that chaos, someone mentions, "Oh hey, mouse_x and _y aren't working."
Then they got it fixed two seconds later. I'm sure their day was ruined by it.

(http://www.idiomsbykids.com/taylor/mrtaylor/class20022003/idioms/idioms2003/Make%20A%20Mountain%20Out%20Of%20A%20Male%20Hill.jpg)
Title: Re: Proposal for guidelines on changes to the master branch of enigma-dev/enigma-dev
Post by: Josh @ Dreamland on June 05, 2013, 08:21:27 PM
I didn't say that the issue ruined anyone's day (Even though I strongly implied it ruined mine). I said it was an issue. An issue that could have been easily avoided by using a branch. Four steps here:
From there, all anyone has to do is check out your branch, implement a fix, and merge the branch back into master. Now no one ever has to incur a problem.
Title: Re: Proposal for guidelines on changes to the master branch of enigma-dev/enigma-dev
Post by: IsmAvatar on June 05, 2013, 10:31:44 PM
Also, if you've already made some code, but haven't committed it yet, but are ready to, you can still checkout the branch. So the first two steps can be done out of order.
So for example, I'm going to start moving mouse_x and mouse_y. I'm not sure how much work is involved, but it seems fairly simple. So I'm on master, I start work, and then the end of the day rolls around and I realize that I'm going to have to commit broken code. That's ok, just
Code: [Select]
git checkout -b moving_mouse and then
Code: [Select]
git commit -m "moving mouse. Shit done broke."
If, however, you already committed to master (but haven't pushed hopefully), not a big deal, just a couple more steps. Create your branch. At this point, both master and the branch will have the commit. We don't want master to have the commit yet, so we're going to roll him back. If you have any uncommitted changes, please make sure to commit or shelve them first, as they will be lost.
Code: [Select]
git checkout master
git reset --hard HEAD^
git checkout moving_mouse
Add more carets after HEAD according to how many commits you made (e.g. 2 commits = HEAD^^). Alternatively, you can just name the commit before yours in place of HEAD^.
Title: Re: Proposal for guidelines on changes to the master branch of enigma-dev/enigma-dev
Post by: Goombert on June 06, 2013, 01:07:48 AM
Ha Ism, try [ ] not <>
Title: Re: Proposal for guidelines on changes to the master branch of enigma-dev/enigma-dev
Post by: polygone on June 06, 2013, 06:23:07 AM
I didn't say that the issue ruined anyone's day (Even though I strongly implied it ruined mine).
Yes it seems to only be you and Robert that it affected, even though neither of you were actually needing it to develop anything. It seems to me that's your own fault for having a bad perspective and not knowing what's going on correctly with ENIGMA.
Title: Re: Proposal for guidelines on changes to the master branch of enigma-dev/enigma-dev
Post by: TheExDeus on June 06, 2013, 07:57:12 AM
I am pretty sure this is all blown out of proportion and I would personally not care about any of this. I don't think anything has to change because of this. I am just happy that there is actually progress that involves more than one person. In the past several years there were brief times of progress that was a doing of one person (like when I came and did drawing functions and path functions while no one else committed anything for 6 months). So this is a good change indeed. And it did work on Windows, which I care about. Josh didn't care for windows for years, so I won't care for linux either. So poly, break it.
Title: Re: Proposal for guidelines on changes to the master branch of enigma-dev/enigma-dev
Post by: IsmAvatar on June 06, 2013, 10:13:12 AM
Can we try to keep this on topic? If you want to discuss aa smoothing, do so in another topic.

JOSH-EDIT: Split the topic. Posts about AA are now in THIS topic (http://enigma-dev.org/forums/index.php?topic=1290.0).
Title: Re: Proposal for guidelines on changes to the master branch of enigma-dev/enigma-dev
Post by: forthevin on June 06, 2013, 12:31:58 PM
polygone: Thanks for the info, that is very useful.

Josh: So basically, bug fixes flow from the branch master to testing to development, while new features and additions flow the other way. That should make things more stable and let us spend less time on regressions, but it would also make development and addition of new features slower more cumbersome. I still think it is too early to adopt such a system, though I agree that adopting a process that increases stability is a good idea at this point in time.
Also, I added a link to your post regarding using git in the guidelines.

IsmAvatar: I added a link to your post regarding using git as well.

After giving it some thought, I think it may make sense to make a simple to follow and understand policy regarding committing to the master branch, and then referring to these guidelines as to the overall thoughts and purpose behind it, as well as for recommended ways to follow the policy. I think the policy would go something like:


By having a policy we can avoid discussing a specific action and instead just refer to the policy, and then discuss the policy separately if there is disagreement about it. The policy doesn't cover everything, but it does cover the minimum, and I think that allows a fair amount of flexibility while still being somewhat effective. What do you think?
Title: Re: Proposal for guidelines on changes to the master branch of enigma-dev/enigma-dev
Post by: IsmAvatar on June 06, 2013, 03:28:01 PM
Looks good. This information should go on the wiki, under something like ENIGMA:Developing (https://enigma-dev.org/docs/Wiki/ENIGMA:Developing)
Title: Re: Proposal for guidelines on changes to the master branch of enigma-dev/enigma-dev
Post by: forthevin on June 08, 2013, 08:34:22 AM
I have written the guidelines and the policy into the wiki under the page IsmAvatar linked.
Title: Re: Proposal for guidelines on changes to the master branch of enigma-dev/enigma-dev
Post by: Goombert on June 08, 2013, 05:19:57 PM
forthevin, I want you to add two things to this.

1) When making bug reports, people should include exact steps to replicate, and properly label issues on the tracker, take LGM's tracker as an example, I had a very pleasant experience working with IsmAvatar's tracker. ENIGMA's tracker on the other hand is a complete mess, when we implement stuff or fix bugs we never mark off the issue # the commit fixes or anything like that, that I was doing on LGM's tracker, not to mention we have polygonz in charge of labeling ^_^

2) When merging I think we need to add that people should make an effort to understand the code and actually review it before merging. It is like writing an essay, you can't proof read your own stuff well, it is best when someone else does it for you. This is also one of the big things of having SVN and a tracker, but yet we do not utilize it, even Josh has done this by merging cheeseboy's half broken code without reviewing that I had to go fix immediately for him.
Title: Re: Proposal for guidelines on changes to the master branch of enigma-dev/enigma-dev
Post by: forthevin on June 10, 2013, 02:49:59 PM
Hey Robert, I think you have some good suggestions. I have added a bit to the wiki in regards to the exact steps to replicate on the page about bug reporting, and I have made a new page on working with issues in GitHub. About reviewing changes, that part is actually already in the guidelines on changing.
Title: Re: Proposal for guidelines on changes to the master branch of enigma-dev/enigma-dev
Post by: Goombert on June 10, 2013, 03:36:14 PM
Wonderful forthevin! Thanks for all your help, I have already taken to doing so as well, tracker looks better already  (Y)