How to work with Github code

[slspencer]

Continuing the discussion from Issues are restored, and we've moved to Github!:

@yannlossouarn

Ok, great! What is the recommended Git client? Could someone describe the recommended procedure for becoming a contributor? I mean, shall we fork the repository, or commit directly into the main repository?

[slspencer]

Basics about the main repo:

• Feature branch = latest code (eg test code) - on your local clone, you will checkout this branch to create your branch for code commits
• Develop branch = released code + patches - don’t use this branch
• Master branch = Doxygen documentation for Develop branch - don’t use this branch

Follow @schwowsers’ instructions for creating your Github repo and local clone, in the next post below.

Additional advice:

1. Before making code changes: Build the Feature branch on your pc with Qt to test that you have all dependencies, paths are defined, etc. Run your valentina.exe at the command line to prove that it works.
2. After making code changes: Build your branch in Qt & run your valentina.exe from the command line. Test how to make it fail, then fix it. There’s no glory in submitting a pull request for untested code.

[slspencer]

Here is info from the previous thread:

@schwowsers

Hey @yannlossouarn, I think the process remains the same as it did with Mercurial & Bitbucket.

• Create a GitHub account.
• Fork the project’s GitHub repository.
• Clone your fork to your local machine.
• Add the main project repo (upstream) to your clone as a remote repo. See here.
• Commit changes to your local repo.
• Pull from upstream and resolve any merge conflicts.
• Push changes to your fork on GitHub.
• Create a pull request.

I plan to update the wiki material for contributors to reflect the move and make things clearer. Also, I take it Steve is the new project maintainer, so if you’re reading this, welcome Steve!

[slspencer]

Steve is temporarily helping out, he won’t be the maintainer. But he’ll always be my better half.

[slspencer]

@yannlossouarn You can install git and run it from the command line. It comes with two visual tools: git-gui for commits, gitk for browsing. Download git from here: https://git-scm.com/downloads\

If you don’t like git-gui or gitk you could try some of these visual git interfaces:
https://git-scm.com/downloads/guis

[yannlossouarn]

It is ok, at this point I succeeded in forking/cloning with GitKraken, and compiled successfully ! I now have to import changes I initiated on Valentina repository.

Bye, Yann

[fabrice]

There is one thing to check if peoples start to contribute: how is handled line return and indentation ?

We can setup Git to prevent bad things.

Look like dismine was using (good) Unix convention \n and spaces.

[ronanletiec]

@slspencer

Basics about the main repo:

Feature branch = latest code (eg test code) - on your local clone, you will checkout this branch to create your branch for code commits

Develop branch = released code + patches - don’t use this branch

Master branch = Doxygen documentation for Develop branch - don’t use this branch

I’ve got a question about this. For the last issues I worked on with dismine, I did my changes and commits on the develop branch. I thought it was this branch that was the latest code, not the feature branch. @slspencer can you correct me if I’m wrong, or update your description? Thank you!

[schwowsers]

I had questions about that, too, @ronanletiec. According to the wiki and the CONTRIBUTING.md file in the repo, the develop branch is generally the one to use as a baseline for new changes. I think we can do away with the generic, long-lived feature branch in the new Git repo, too. I believe its existence was due to the way Mercurial handles branches, but now that we’ve switched to Git I think it can be closed.

There also appears to be an issue with the AppVeyor auto build setup, but that’s unrelated to branches.

[slspencer]

Yeah, let’s follow the Gitflow workflow as described in the How it Works sections in this tutorial. https://www.atlassian.com/git/tutorials/comparing-workflows

[ronanletiec]

The link you provided is a really good and comprehensible explanation of the workflow we should have! I recommend the developers to read it!

We should go on working with the “forking flow”, so that every developer has its own public repository, and as you said work with the “GitFlow” for the branching workflow.

The feature branch can probably be closed.

Depending on what’s exactly in those branches, if the release branch is the branch of the last version released, it should be merged into the master and then closed.

What is the gh-pages branch for?

[slspencer]

gh-pages is to generate the Doxygen docs so that they are viewable as a webpage

[slspencer]

The feature branch has been deleted. We’re now following a ‘best practices’ standard workflow. This should make it easier for people to submit changes.

[ronanletiec]

@kmf

must one make a fork and or pull request before one can commit?

@kmf I responde to you in a more appropriated topic. Maybe you already figured out an answer to your question in the meantime.

I see you already made a fork. Your commits should be made in your fork, maybe creating a new branch based on develop, you could call your branch “tape-refactoring” for instance. When everything is up and running you could merge it to your develop branch, and then ask for a pull request to the original repository.

You can read the documentation that slspencer posted, it’s very good to understand the workflow we should work with:

@slspencer

Yeah, let’s follow the Gitflow workflow as described in the How it Works sections in this tutorial. Git Workflow | Atlassian Git Tutorial

[kmf]

At some point, somebody may have to do “configuration management” to the point of resolving changes that touch a single source file, an interface, or closely couples functions.

At this point, if I go offline for 2 months and work on tape (mid october to mid december) I hope it is unlikely that I would impact the work of anybody else

[slspencer]

Resolution of changes is handled during the merge of a contributors’s branch into the develop branch by the maintainer (currently me).

[kmf]

I am out of likes for the day but I am glad to know that you can do the resolution of changes. I am confident that you can be aware enough of what is likely (or not) to cause “regression” and keep it under control