Contribution Workflow
GCentral is open-source, so feel free to fork the project and use it for your own purposes. If you want to contribute back to GCentral by developing code or fixing bugs, we're tremendously grateful.
The workflow defined below is there to set everyone's expectations so that we can maintain good standards and facilitate contribution integration in the future released versions.
The GCentral Website project uses the Forking workflow to collaborate between devs. Each developer works from their own fork of the Website repository where they'll create new feature branches that can be merged into the develop branch on the official repository.
If you're first getting started you should head over to our Environment Setup page to get an appropriate development environment with a local test webserver setup.
When you contribute to GCentral you will use the Forking workflow. You can find a detailed description of this workflow provided by Atlassian here. The first step is to make sure you have your own fork of the official Website repository and clone that to your development environment. If you need guidance on forking within GitHub you can check out our environment setup documentation here.
The official Website repository has 2 main branches: master and develop. Master contains the history of the releases and the develop branch contains all of the project history including new features that haven't been released yet. As a contributor you'll only be concerned with the develop branch where you can pull in all the existing features and new features that have been merged since you started working on your feature.
After you've created your fork and cloned your copy to your development environment you'll need to add the official Website repository as an additional remote to your local clone. This is typically named upstream and will let you pull in work from the official repository that was merged after you started work on your new feature.
When you want to start working on a new feature for the project you'll create a new branch in your repository to save your work in. These "feature branches" should be atomic in that they only contain related updates. If two features don't rely on each other they should be developed in separate branches. This makes it much easier for the GCentral maintainers to review pull requests and perform testing. Inevitably some work will involve quite large features that may require work from multiple developers but the goal is to always remain as concise as possible.
Before you do a Pull Request to get your feature added to the main repository you need to make sure your code base is up to date with any changes that may have taken place on the main repository. You can do this by performing a pull from the upstream/develop branch into your feature branch; Git does not restrict you to pulling from the same remote/branch as you're working in. It is your responsibility to ensure your feature does not break other features that have already been merged into the main repository. At some point, especially early on in the project, it is inevitable there will have been updates to the main repository that conflict with changes you've made to implement your feature. If you need to make changes to already merged code to get your feature to work these must be discussed to ensure changes don't break other features already in use or in development.
Just like a secondary remote was added as upstream to point your local clone back to the official repository, additional remotes can be added to point to other developers' forks. This way as each developer makes changes that they push to their fork, the changes can be pulled into your local clone. Features in active development can have their code shared among multiple developers this way.
New developers joining existing effort on a feature can start by forking another developer's fork to easily obtain work already completed on that feature. If you've already setup your local clone you can add another developer's fork as a remote to your clone, fetch their new feature branch, and checkout that branch in your local clone to begin working.
Alternatively, a group of developers can work within a common repository and all push/pull with the same remote. This is simpler to use while performing the development on the feature but will require additional management of the repository on GitHub.
With either method there will be 1 repository fork that the Pull Request is submitted from once the feature is completed. Duplicate Pull Requests will be denied to give a chance for the developers to make sure the correct PR has been submitted.
You'll be making a Pull Request to inform GCentral's maintainers that you wish to merge your contribution into GCentral's repository. This is initiated from your fork that contains your new feature branch. When setting up your pull request you'll want to make sure it's pointed at base: develop(Red) and is coming from the correct fork (Green) and from the correct branch you've been developing on (Blue).
An incoming pull request automatically creates a new issue for the team to review. As part of your pull request, please add comments that describe what bug or feature you've tackled and how you fixed it. If you've been working on an issue that was submitted to the project's issue list please include the specific issue number in the pull request description.
The next step will be to do a code review on your contribution. If GCentral's dev team accepts it, your contribution will be merged to the development branch. If there are modifications to make to your proposal in order to make it acceptable for merging, the team and the community can all comment and help make it happen.
If, for some reason, your contribution cannot be accepted, your pull request will be closed without being merged. There are many reasons why this could happen: maybe you've worked on a feature that someone else already solved, or maybe the implementation you are proposing are not scalable or do not meet the community's needs. If that's the case, we hope that GCentral's community and core developers will help you learn and grow as a developer.
Our vision is:
- To enable the LabVIEW community to make the best version of itself.
- To improve our community's capability by removing barriers to collaboration.
This is a fundamental aspect of GCentral. We hope everyone feels welcome and grows in the process.
GCentral will be following GitFlow for development and release. As such, you will always find the production version of GCentral's website and indexer in the "master" branch. The latest approved development code will be in the "develop" branch. The develop and master branches could be synchronized, but this is not a certainty. For example, version 1.0 might be running on GCentral's server, but we might have been actively developing version 1.1 for a while, whereas the tip of the develop branch might be several commits ahead of the production code.
When GCentral's core development team will be deploying a new version, it might be in a "beta release" branch for a while if the proposed changes need to be tested before deployment in production.
As a good practice, remember to always develop from the tip of "develop" branch.