Best Practices for Git Repositories on Open Source Projects

Best practices for git repositories on open source projects

Some tips I've learned from a similar situation:

• Have a remote tracking branch for the upstream author's work.
• Pull changes from this tracking branch into your master branch every so often.
• Create a new branch for each of the topics you're working on. These branches should generally be local only. When you get changes from upstream into master, rebase your topic branches to reflect these changes.
• When you're done with some topic work, merge into master. This way, people who are deriving work from yours, will not see too much rewritten history, since the rebasing occurred in your local topic branches.
• Submitting changes: Your master branch will basically be a series of commits, some of which are the same as upstream, the rest are yours. The latter can be sent as patches if you want to.

Of course, your choice of branch names and remotes are your own. I'm not sure these are exhaustive to the scenario, but they cover most of my hurdles.

Are there best-practice guidelines for maintaining a repository?

The Cloud Native Computing Foundation (CNCF) serves as the vendor-neutral home for many of the fastest-growing open source projects, including Kubernetes, Prometheus, and Envoy.

As such, it can be used as a starting point for your own project: see contribute.cncf.io/maintainers/github/, which offers:

• template, to be usre you have your README, LICENSE and other important files.
• labels, to better classify your issues

Add also a clear "release and maintenance policy", and you should be in good shape.

Best Practice for Git Repositories with multiple projects in traditional n-tier design

The reason most people advise to do separate repositories is because it separates out changes and change sets. If someone makes a change to the client projects (which you say doesn't really effect others), there is no reason for someone to update the entire code base. They can simply just get the changes from the project(s) they care about.

Git Submodules are like Externals in Subversion. You can set up your git repositories so that each one is a separate layer, and then use submodules to include the projects that are needed in the various hierarchies you have.

So if for example:

/Core -- It's own git repository that contains it's base files (as you had outlined)
  /SharedLib1
  /SharedLib2

/UI Layer -- Own git repository 
  /CoreWebsite
  /WebsiteHelper
  /Tahiti.WebsiteHelpers
  /Core -- Git Submodule to the /Core repository
    /SharedLib1
    /SharedLib2

This ensures that any updates to the /Core repository are brought into UI Layer repository. It also means that if you have to update your shared libraries you don't have to do it across 5-6 projects.

Best way to reuse just a small set of files from another Open-Source project?

If you really need to keep a strong link between some files of a repository and your own project repo, I would:

• add a fork of the first repository as a submodule inside my own project repository
• use symlinks inside my project for the few files I need (symlink to the submodule required file)

That way:

• I can use those files anywhere inside my project
• each time I modify them, I actually change their content in the submodule repository, which makes it easier to identify the change, and make a pull request

Best practices on GitHub repos, to Fork or create a New Branch

To me, the best practice when dealing with a project with more than one developer, is to use gitflow branching model.

First, the master branch will now only be used to keep track of the releases of your app, major, minor or patch versions, following the Semantic Versionning.

The develop branch will be the core of your project, since it will make the bridge between the different features and your releases.

This system helps to reduce the number of merge, just as a simple branching system will do, but add the semantic logic, and the friendly and simple commands that comes with it.

For more info about gitflow you can follow this link.

Best Practices for Setup and Management of an Open Source Project

I'm just getting started in community projects, but I'll give you some advice on what I know.

How do I setup and automate a one step submit-test-commit-generate API docs-push update to website process?

I've never implemented it as one process. You could just have a checklist, and possibly even create some scripts to do certain tasks. I've never worked with any source control that automates the uploading and such to be done by a script. Most of the time, there is some web interaction to be involved.

You don't want to push API changes until it's an official release.

EDIT: Working Environment

For PHP, most of the time, I either edit directly on the server and test it there, using a beta.example.com, or similar, before pushing to example.com. You could also set up an web environment on your home PC (using XAMPP for Windows, or the standard LAMP installation on Linux). You would probably just use a mirror of your repository here, so you'd do svn commit, or whichever is appropriate for the VCS or DVCS you choose.

The fun part is testing this with different PHP versions. I've not done this myself, but you could probably use a .htaccess file to run a different PHP binary in order to test it out. I'm not really sure what the best option is for this is.

I've not done much with API, as I've never created a library, but just doing a quick search I found http://www.phpdoc.org/. It looks like a mature project, so that might be a starting point.

As far as creating releases go, I generally create a script that only includes the files that are part of the distribution (it will filter out any VCS files, and anything that you don't want in the distributed file). You could write a script around find on linux (which is what I do most of the time), or there may be other better options.

How do I handle (technically) submissions from other users? How can I ensure that those submissions must be approved before being integrated?

This is mostly handled by the bug tracker, and limited access in the Version Control System. Usually, you, and the people you allow, can commit to the VCS. Other users can submit patches, but then you might have someone review the patch, test the patch, and commit. You could split these tasks up as a team, or assign a patch to one person and have them do it all.

What are some of the pitfalls that can be avoided in terms of the project community? I'd prefer to have it be as friendly and helpful as possible without a lot of drama.

I would just make sure to keep it as positive as possible with the project members and community. There's going to be some disagreements, and it will drive a few people away, but as long as you have a stable product that meets the needs of most people, I think that's all that anyone can expect.

---

Related Topics