Kubos Contribution Process ========================== This is the workflow you should go through in order to create and complete a task to contribute to the KubOS project Sign the CLA ------------ All contributors must sign the Kubos Contributor License Agreement before their changes can be merged into the main codebase. The Kubos CLA can be found `here `__. Create an Issue --------------- GitHub issues allow us to track what problems have been found and which problems are currently being addressed. - Navigate to the repo you'd like to open an issue against (most likely kubos/kubos) - Click the 'Issues' tab - Click the 'New Issue' button - The title should be a descriptive overview of the problem - The description should go into more detail about what the problem/feature is and what needs to be done in order to complete the task. - If you are creating a story, the description should follow the `Agile user story template `__ - Click the 'Labels' link and add a tag for 'Bug' or 'Enhancement' depending on what kind of work should be done Mark the Issue as 'In Progress' ------------------------------- In order to track what's being worked on and by whom, for every issue you work you should: - Click the 'Assignees' link and select yourself - Mark the issue as 'In Progress' by editing the title of the project and adding "[WIP]" Create a Branch of the Code You Want to Work On ----------------------------------------------- All code changes should initially be made in a branch of the relavent Kubos repo either in the main repo, or in a personal copy (if you don't have access) and then be submitted against the master branch as a pull request: To create your own repo: - Navigate to the GitHub page of the main code that you want to work on. For example, https://github.com/kubos/kubos. - Click the 'Fork' button in the upper right-hand corner. - If you see a dialog 'Where should we fork this repository?', click the icon with your username. - Within your development environment, create a link to your new remote repository: $ git remote add {remote name you create} {personal repo url} Clone the repo that you want to modify onto your local machine :: $ git clone http://github.com/kubos/kubos Move into the repo folder :: $ cd kubos Create a local branch to make your changes :: $ git checkout -b {local branch name you create} Make Your Changes ----------------- The code. Write it. Test it. The :doc:`Kubos Standards ` doc has some basic naming and coding standards that should be adhered to. When in doubt, try to match the styling of the surrounding code. Update any documentation areas that are affected by your changes. For instance, if you found that a UART configuration option was not available for a certain board type, you would edit kubos-hal/kubos-hal/uart.h in the appropriate comment section with a new note about the unsupported option. - If you want to test your documentation changes: - Run the command 'doxygen Doxyfile' from the project folder with the new documentation to regenerate the html documentation - Open up {project}/html/index.html in a web browser - Browse to your doc updates to verify Add or update any unit tests that are affected by your changes. For instance, if support for SPI is added for the Kubos Linux HAL, then a new test folder would be added to `hal/kubos-hal/test` with the relavent new test cases. Commit your changes and push to your remote branch (the branch will be created automatically if it doesn't exist): :: $ git add {files you changed} $ git commit -m "Descriptive message about the changes you made" $ git push {remote name} {local branch name} If you're committing against a Kubos repo, then the remote name will likely be "origin". If you're committing against your personal fork, then the remote name will match what you specified in the ``git remote add`` command. `Commit early, commit often `__ Create a Pull Request --------------------- At some point, you'll want to create a pull request so that your changes can be merged into the main repo's master branch. You will need to create a pull request for each repository you are making changes to. From the GitHub page for the repository that contains the changes you want to merge: - Click the 'Branch:' dropdown on the left-hand side and select the local branch containing your changes - Click the 'New pull request' button - The title of the pull request should clearly refer to its corresponding issue - In the description field, add a small summary of the changes you made. The title should have indicated the bulk of the changes you made, but it's also good to mention things like documentation updates and any miscellaneous changes that were made (for example, fixing any bugs that you ran into while working on your code changes). - Click 'Create pull request' If you'd like specific people to review your code, you can either mention them in the description with an ``@{name}`` tag, or by adding them to the 'Reviewers' list. You are welcome to create a pull request before your changes are entirely complete. Creating a pull request early in the code-creation process allows others to see what changes are being made and answer questions or offer architectural suggestions. If you do create a pull request before you are done making changes, add "[WIP]" to the pull request's title. Remove the "[WIP]" once all code changes have been completed and the PR is officially ready for review. Merge in New Changes From Master -------------------------------- After submitting your pull request, you may find that GitHub has flagged one or more files as being in conflict with the current version of the file in the master branch. This means that someone else has committed code in the same file and similar area as you and your changes can't be automatically merged. In order to resolve the conflict, execute the following steps within your development environment: Merge the master branch into your local branch :: $ git checkout origin/master $ git pull origin master $ git checkout {local branch where your changes are} $ git merge origin/master Git will edit any files with conflicts. Conflicts will look like this: :: >>>Head New local changes ========== New master changes <<