From cc31cc37a186957cefe39a78ad8878ff3de53e40 Mon Sep 17 00:00:00 2001 From: Jordan Musser Date: Wed, 29 Mar 2023 10:16:37 -0400 Subject: [PATCH] Adding reference documentation --- .../merge_request_templates/basic_template.md | 26 ++ CONTRIBUTING.md | 276 ++++++++++++++++++ DISCLAIMER | 31 ++ UNLICENSE | 24 ++ 4 files changed, 357 insertions(+) create mode 100644 .gitlab/merge_request_templates/basic_template.md create mode 100644 CONTRIBUTING.md create mode 100644 DISCLAIMER create mode 100644 UNLICENSE diff --git a/.gitlab/merge_request_templates/basic_template.md b/.gitlab/merge_request_templates/basic_template.md new file mode 100644 index 0000000..465e621 --- /dev/null +++ b/.gitlab/merge_request_templates/basic_template.md @@ -0,0 +1,26 @@ +## Instructions + +- Put an `x` into all boxes relevant to your _merge request_ +- Use the _Preview_ tab to review your _merge request_ + +## Summary + + +## Additional information (optional) + + +## Checklist + +The proposed changes: +- [ ] fix a bug or incorrect behavior +- [ ] add new capabilities or features +- [ ] changes answers in the test suite to more than roundoff level +- [ ] are likely to affect the results of downstream users +- [ ] include documentation in the code + + +## Release acknowledgement + +In order for a merge request to be accepted, each piece of code must be in public domain or released under [Unlicense](http://unlicense.org/). Check one of the following options: +- [ ] I am the original author of this code and I release it under [Unlicense](http://unlicense.org/) +- [ ] I am not the original author of this code but it is in public domain or released under [Unlicense](http://unlicense.org/). (Supporting evidence required.) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..8ca72f4 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,276 @@ +## Development Model + +Development generally follows the following ideas: + + * New features are merged into to the `main` branch using + Merge Requests (MRs). + + Nightly regression testing is used to ensure that no answers + change (or if they do, that the changes were expected). + + * Bug fixes, questions and contributions of new features are welcome! + + * Bugs should be reported through GitLab Issues. + * All contributions should be done via merge requests. + A merge request should be generated from your fork + target the `main` branch. See below for + details on how this process works. + + In general we squash commits upon merge to have a clean history. + *Please ensure that your MR title and first post are descriptive, + since these will be used for a squashed commit message.* + + Please note the following: + If you choose to make contributions to the code + then you hereby grant a non-exclusive, royalty-free perpetual license + to install, use, modify, prepare derivative works, + incorporate into other computer software, + distribute, and sublicense such enhancements or derivative works + thereof, in binary and source code form. + + * On the first workday of each month, we make a tagged release. + +## Git workflow + +This project uses [git](https://git-scm.com) for version control. If you +are new to git, you can follow one of these tutorials: +- [Learn git with bitbucket](https://www.atlassian.com/git/tutorials/learn-git-with-bitbucket-cloud) +- [git - the simple guide](http://rogerdudler.github.io/git-guide/) + +### Make your own fork and create a branch on it + +The basic workflow is: +- Fork the main repo (or update it if you already created it). +- Implement your changes and push them on a new branch `` on +your fork. +- Create a Merge Request from branch `` on your fork to branch +`main` on the main csg-eb repository. + +First, let us setup your local git repo. To make your own fork of the main +(`upstream`) repository, press the fork button on the [MFIX GitLab page](https://mfix.netl.doe.gov/gitlab/exa/csg-eb). + + +``` +git clone https://mfix.netl.doe.gov/gitlab//csg-eb.git + +# Then, navigate into your repo, add a new remote for the main csg-eb repo, and fetch it: +cd csg-eb +git remote add upstream https://mfix.netl.doe.gov/gitlab/exa/csg-eb +git remote set-url --push upstream https://mfix.netl.doe.gov/gitlab//csg-eb.git +git fetch upstream + +# We recommend setting your development branch to track the upstream one instead of your fork: +git branch -u upstream/main +``` + +> Note: you do not have to re-do the setup above every time. +> Instead, in the future, you need to update the `main` branch +> on your fork with +> ``` +> git checkout main +> git pull +> ``` + +Make sure you are on the `main` branch with +``` +git checkout main +``` +in the csg-eb directory. + +Create a branch `` (the branch name should reflect the piece +of code you want to add, like `high_order_interpolation`) with +``` +git checkout -b +``` +and do the coding you want. +Add the files you work on to the git staging area with +``` +git add +``` +### Commit & push your changes + +Periodically commit your changes with +``` +git commit -m "This is a 50-char description to explain my work" +``` + +The commit message (between quotation marks) is super important in order to +follow the developments and identify bugs. + +For the moment, commits are on your local repo only. You can push them to +your fork with +``` +git push --set-upstream origin +``` + +If you want to synchronize your branch with the `main` branch (this is useful +when `main` is being modified while you are working on +``), you can use +``` +git pull upstream main +``` +and fix any conflicts that may occur. + +Do not merge your branch for MR into your local `main` branch, +because it will make your local `main` branch diverge from the +matching branch in the main repository after your MR is merged. + +### Submit a Merge Request + +A Merge Request is the way to efficiently visualize the changes you made +and to propose your new feature/improvement/fix to csg-eb. +Right after you push changes, a banner should appear on the GitLab page of +your fork, with your ``. +- Click on the `Create merge request` button to prepare your MR. +- It is time to communicate your changes: write a title and a description for +your MR. People who review your MR are happy to know + * what feature/fix you propose, and why + * how you made it (created a new class than inherits from...) + * and anything relevant to your MR (performance tests, images, *etc.*) +- Press `Create merge request`. Now you can navigate through your MR, which +highlights the changes you made. + +Please DO NOT write large Merge Requests, as they are very difficult and +time-consuming to review. As much as possible, split them into small, +targeted MRs. +For example, if find typos in the documentation open a merge request that only fixes typos. +If you want to fix a bug, make a small merge request that only fixes a bug. +If you want to implement a large feature, write helper functionality first, test it and submit those as a first merge request. +If you want to implement a feature and are not too sure how to split it, +just open a discussion about your plans and ping other csg-eb developers on it to chime in. + +Even before your work is ready to merge, it can be convenient to create a MR +(so you can use GitLab tools to visualize your changes). In this case, select +the option "Mark as draft" after creating the MR. + +Once your merge request is made, we will review and potentially merge it. +We recommend always creating a new branch for each merge request, as per the above instructions. +Once your merge request is merged, you can delete your local MR branch with +``` +git branch -D +``` + +and you can delete the remote one on your fork with +``` +git push origin --delete +``` + +Generally speaking, you want to follow the following rules. + + * Do not merge your branch into your local `main` branch that tracks csg-eb + `main` branch. Otherwise your local `main` branch will diverge from csg-eb + `main` branch. + + * Do not commit in your `main` branch that tracks csg-eb `main` branch. + + * Always create a new branch based off `main` branch for each merge request, unless you are + going to use git to fix it later. + +If you have accidentally committed in `main` branch, you can fix it as follows, +``` +git checkout -b new_branch +git checkout main +git reset HEAD~2 # Here 2 is the number of commits you have accidentally committed in development +git checkout . +``` +After this, the local `main` should be in sync with csg-eb `main` and your recent +commits have been saved in `new_branch` branch. + +If for some reason your MR branch has diverged from csg-eb, you can try to fix it as follows. Before +you try it, you should back up your code in case things might go wrong. +``` +git fetch upstream # assuming upstream is the remote name for the official csg-eb repo +git checkout -b xxx upstream/main # replace xxx with whatever name you like +git branch -D main +git checkout -b main upstream/main +git checkout xxx +git merge yyy # here yyy is your MR branch with unclean history +git rebase -i upstream/main +``` +You will see something like below in your editor, +``` +pick 7451d9d commit message a +pick c4c2459 commit message b +pick 6fj3g90 commit message c +``` +This now requires a bit of knowledge on what those commits are, which commits have been merged, +which commits are actually new. However, you should only see your only commits. So it should be +easy to figure out which commits have already been merged. Assuming the first two commits have been +merged, you can drop them by replace `pick` with `drop`, +``` +drop 7451d9d commit message a +drop c4c2459 commit message b +pick 6fj3g90 commit message c +``` +After saving and then exiting the editor, `git log` should show a clean history based on top of +`main` branch. You can also do `git diff yyy..xxx` to make sure nothing new was dropped. If +all goes well, you can submit a MR using `xxx` branch. +Don't worry, if something goes wrong during the rebase, you an always `git rebase --abort` and start over. + +## csg-eb Coding Style Guide + +### Code Guidelines + +csg-eb style guidelines follow the AMReX coding style. + +Developers should adhere to the following coding guidelines: + * Indentations should use 4 spaces, not tabs. + * Use curly braces for single statement blocks. For example: +```cpp + for (int n=0; n<10; ++n) { + Print() << "Like this!"; + } +``` + or +```cpp + for (int n=0; n<10; ++n) { Print() << "Like this!"; } +``` + but not +```cpp + + for (int n=0; n<10; ++n) Print() << "Not like this."; +``` + or +```cpp + for (int n=0; n<10; ++n) + Print() << "Not like this."; +``` + * Add a space after the function name and before the +parenthesis of the parameter list (but +not when simply calling the function). For example: +```cpp + void CorrectFunctionDec (int input) +``` + Not +```cpp + void IncorrectFunctionDec(int input) +``` + This makes it easy to find where functions are defined with grep. + * Member variables should be prefixed with `m_`. For example: +```cpp + amrex::Real m_variable; +``` +These guidelines should be adhered to in new contributions, but +please refrain from making stylistic changes to unrelated sections of code in your MRs. + + + +## Core Developers + +People who make a number of substantive contributions will be named +"core developers" of csg-eb. The criteria for becoming a core +developer are flexible, but generally involve one of the following: + + * 100 non-trivial commits to `csg-eb/src/` *and/or* + + * addition of a new algorithm / module *and/or* + + * substantial input into the code design process or testing + +If a core developer is inactive for multiple years, we may reassess their +status as a core developer. + +The current list of core developers is: +Mark Meredith, +Jordan Musser (NETL), +Deepak Rangarajan (NETL) diff --git a/DISCLAIMER b/DISCLAIMER new file mode 100644 index 0000000..e402d28 --- /dev/null +++ b/DISCLAIMER @@ -0,0 +1,31 @@ +This report was prepared as an account of work sponsored by an agency +of the United States Government. Neither the United States Government +nor any agency thereof, nor any of their employees, makes any +warranty, express or implied, or assumes any legal liability or +responsibility for the accuracy, completeness, or usefulness of any +information, apparatus, product, or process disclosed, or represents +that its use would not infringe privately owned rights. Reference +herein to any specific commercial product, process, or service by +trade name, trademark, manufacturer, or otherwise does not +necessarily constitute or imply its endorsement, recommendation, or +favoring by the United States Government or any agency thereof. The +views and opinions of authors expressed herein do not necessarily +state or reflect those of the United States Government or any +agency thereof. + + +This project was funded by the United States Department of Energy, +National Energy Technology Laboratory, in part, through a site support +contract. Neither the United States Government nor any agency +thereof, nor any of their employees, nor the support contractor, nor +any of their employees, makes any warranty, express or implied, +or assumes any legal liability or responsibility for the accuracy, +completeness, or usefulness of any information, apparatus, product, +or process disclosed, or represents that its use would not infringe +privately owned rights. Reference herein to any specific commercial +product, process, or service by trade name, trademark, manufacturer, +or otherwise does not necessarily constitute or imply its endorsement, +recommendation, or favoring by the United States Government or +any agency thereof. The views and opinions of authors expressed +herein do not necessarily state or reflect those of the United States +Government or any agency thereof. diff --git a/UNLICENSE b/UNLICENSE new file mode 100644 index 0000000..68a49da --- /dev/null +++ b/UNLICENSE @@ -0,0 +1,24 @@ +This is free and unencumbered software released into the public domain. + +Anyone is free to copy, modify, publish, use, compile, sell, or +distribute this software, either in source code form or as a compiled +binary, for any purpose, commercial or non-commercial, and by any +means. + +In jurisdictions that recognize copyright laws, the author or authors +of this software dedicate any and all copyright interest in the +software to the public domain. We make this dedication for the benefit +of the public at large and to the detriment of our heirs and +successors. We intend this dedication to be an overt act of +relinquishment in perpetuity of all present and future rights to this +software under copyright law. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR +OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +OTHER DEALINGS IN THE SOFTWARE. + +For more information, please refer to -- GitLab