Skip to content

Remove all git guidelines from contributing #21

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
ArwynFr wants to merge 1 commit into
base: master
Choose a base branch
from
Draft

Remove all git guidelines from contributing #21

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
93 changes: 19 additions & 74 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,8 @@

This documentation provides guidelines and standard procedures to contribute to our project. It is a generic documentation which may be overriden on a per-project basis. Please check the `.github\CONTRIBUTING.md` file of projects for additional instructions.

**Note:** the usage of git is beyond the scope of this guide. If you need help in using git, see [our support policy](./SUPPORT.md) on how to get help.

## Ways to contribute to GSRI projects

There are two ways of contributing to our projects :
Expand All @@ -24,81 +26,33 @@ Before submitting the issues ensure you have filled in :
* a description with details
* add either a `bug` or `enhancement` label

If you need help in opening an issue, feel free to come to our Discord.
If you need help in opening an issue, see [our support policy](./SUPPORT.md) on how to get help.

## Occasional contribution to the source code

**Note:** *this procedure is for non-GSRI occasional contributors. As such you are not granted write access to our repository, but you still may provide pull request from forked repositories.*

### Fork the repository

The first step in order to contribute is to fork our repository. This basically means you will create your own copy of our repository. In order to do so, just click on the `Fork` button in the top right of your screen.

That's all.

### Clone the repository

You need to use a git client in order to download and synchronize your work with the repository. If you don't know how to use git, we suggest you use [Github Desktop](https://desktop.github.com/).

Once git client is installed, go to your forked project repository on github.com, and click the green `Clone or download` button on the right side of the webpage, then click `Open in Desktop` in the tooltip. Github Desktop will start and ask you where to download the source code. Select a directory of choice, and once selected, click `Clone` ; Github Desktop will download the sources on your computer.

### Modify the sources

You can now work on the source code with your favorite editor. If you don't have one, we suggest you use [Microsoft Visual Studio Code](https://code.visualstudio.com/), which integrates well with Github Dekstop. If you are modifying a mission, please follow guidelines below on *How to contribute to Arma 3 missions*.

Git has three different features regarding changes tracking :

* `git stage` means you want to consider the current version of a given file *ready to commit*. It is a convenient way to add or remove changes from your current commit.

* `git commit` means your *staged* modifications are stored **locally**. Every commit is associated to your identity and you can add a small description of what you changed, and why. If you did not stage anything, git will stage all changes and commit them.

* `git push` will send your *committed* modifications to github. All modification stay local until you git push. Other users can then access you modifications from their repository. You can also obtain code *pushed* by other people by `fetch`ing from github.

### Keeping repositories synced

You should frequently ensure you're not working on an outdated version of the code base. Please ensure your branch has no *behind* commits relative to our master branch. If your branch is not up-to-date with upstream/master, opening a pull request will be denied by our staff.

If you need to update, you should sync changes from our repository to yours. this operation is called *integration*. When integrating, conflicts may happen, for instance if you modified an entity but it was deleted from upstream by another developer.
This procedure is for non-GSRI occasional contributors. As such you are not granted write access to our repository, but you still may provide pull request from forked repositories.

Conflict resolutions should preferably be done on your currently working branch, as it makes it easier to test wether the integration process did not break anything. Once you're satisfied with the merge, check your version of the code still works OK before opening the pull request. This technique is called *ping-pong merging*.
1. Fork the repository
1. Make change in your own repository
1. Ensure your repository is not behind ours
1. Open a pull request to upstream

### Open a pull request to upstream

Once you're satisfied with your work, and you want it to go to the official version, you can open a pull request to merge your changes *upstream*.

Open the pull request by selecting `Branch` / `Create pull request` in Github Desktop. This will open your browser with a form to fill in. Ensure the source branch is the one you have been working on, and the destination is the master branch of our repository. Once completed, click `Open pull request`.

**Note: All PR to other branches will be denied by our staff.**
There are a few rules for pull request to be deemed valid :
* Your repository must not be behind ours
* Your pull request must target our master/main branch, unless explicit request to do otherwise
* You must provide a meaningfull title to the pull request
* You must provide an exhaustive description on changes

GSRI project administrators will the review your code before merging to production. Depending on the project type, tests and other operations may happen to ensure your code does not break anything. If anything goes wrong or we spot somthing that must be modified, you can commit fixes to your current working branch, this will add changes to the pull request automatically.

## Regular contribution to the source code

**Note:** This procedure is for GSRI members or well known regular contributors. Such people are allowed to contribute directly on the repository to prevent fork proliferation. If you are not allowed to contribute directly to the repository, see instructions in the *occasional contribution to the source code* section above.

### Obtain write access to the repository

Your first step in order to contribute directly is to obtain write access to the repository. Ask on Discord and we will consider granting you write access.

### Clone the repository

If you are a regular contributor, you may contribute directly on our repository. you do not need to fork the repository and you can clone the gsri directory directly.

### Create a new branch
This procedure is for GSRI members or well known regular contributors. Such people are allowed to contribute directly on the repository to prevent fork proliferation. If you are not allowed to contribute directly to the repository, see instructions in the *occasional contribution to the source code* section above.

**Note: This step is mandatory.** Failing to do so will make your modifications on the master branch. You will be allowed to commit locally, but you will be denied pushing to github.

In order to create a new branch, select `Branch` / `New branch ...` in the menu. Github Desktop will ask a branch name. Enter anything you want, such as your nickname or the feature you're planning to implement. If in doubt, ask us. Ensure the source branch is `master`. Once created, publish the branch to github by clicking on the button in the top bar of Github Desktop.

Other operations are similar to above procedure

### Keeping your branch up-to-date with master

You should frequently ensure you're not working on an outdated version of the code base. Please ensure your branch has no *behind* commits relative to our master branch. If your branches are not up-to-date with upstream/master, opening a pull request will be denied by our staff. If changes happened on the master branch, you may use `Branch` / `Update from master` from Github Desktop menu to upgrade. Conflict resolution must be done on your currently working branch as well.

### Open a pull request to master

The procedure is also the same as above. Your repository must be up-to-date with master, or your pull request will be denied. The operation is easier because Github will help you more. Like with forked repository, commits may run tests and operations to ensure your code is correct before allowing merges. Merges are done by GSRI staff. You can commit again to your current working branch to add changes to the PR automatically.
1. Clone repository
1. Create a work branch
1. Ensure your branch is not behind master/main
1. Open a pull request to master/main

## Specific information about ArmA 3 mission contributions

Expand Down Expand Up @@ -126,13 +80,4 @@ This concerns `mission.sqm` files, but also `config.cpp`. Git is good at version

Also, do not add your own generated pbo/binary content, we will be build, rapify, binarize and pack automatically from sources.

If your changes include large binary content (images, audio, video), contact staff so we can decide wether it shall be versionned or hosted on our private cloud for integration.

## A few words of advice

* Always `Fetch from Github` and `Update from master` **before** you work
* Always work on your own branches and then pull request to master
* Commit small changes and add meaningfull descriptions
* Commit changes frequently, this is a near equivalent of a `Ctrl + S`
* Push at least daily, even if your code is broken (better broken than lost)
* Borderless mode makes it easier to switch between game and desktop
If your changes include large binary content (images, audio, video), contact staff so we can decide wether it shall be versionned or hosted on our private cloud for integration.